故障排除

诊断常见错误

每条信息都是 Doconut 实际输出的文字，按症状组织。找到对应错误并应用修复方案。

查看器未显示内容

查看器区域为空，浏览器控制台充满 /doconut-res/... 的 404 错误
UseDoconutResources() 缺失，或放在 UseDoconut() 之后。它必须在管道中首先调用。

出现 HTTP 500，内容如下：

text
Session middleware not configured. Call UseSession() before UseDoconut().

Doconut 的令牌安全（默认开启）需要 ASP.NET 会话状态。请在 Doconut 中间件分支之前添加 builder.Services.AddSession() 和 app.UseSession()。

页面区域出现错误图片，显示内容为：

text
You Are Not Authorized To View This Page.

该令牌是由不同的浏览器会话打开的。常见原因包括：会话 Cookie 未随页面请求发送（跨域设置、SameSite 策略、没有 Cookie 桶的 API 客户端），或应用程序重启（生成新会话密钥）。这是安全层按设计工作的表现——参见核心概念 → 会话与安全。

错误图片显示：

text
Document session not found. Please re-open document.

令牌已过期（滑动窗口，默认 60 分钟 — DocOptions.TimeOut）或会话已关闭。请重新打开文档以获取新的令牌。

打开文档失败

LicenseException 带有拒绝信息 — 找到了许可证文件但被拒绝（签名无效、被篡改、列入黑名单，或构建超出许可证的版本/更新窗口）。此状态会阻止打开（快速失败），而不是降级为水印；请阅读 License.RejectionMessage 了解原因。

LicenseException:

text
This document type requires the 'Dicom' plugin license.

该扩展只能由插件（此处为 DICOM）处理，且相应能力未被授予。请注册插件并验证 lic.IsCapabilityGranted(LicenseCapability.Dicom)。缺失或不足的非临时授权通常会在 AddDoconut() 时提前失败。

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

没有任何查看器（内置、插件或自定义）声明支持该扩展。检查受支持的格式列表；若是自定义格式，可使用 DoconutOptions.RegisterViewer 添加。

InvalidDataException — 文件内容损坏或与其扩展名不匹配（例如文件被改名）。请在打开前验证上传的文件。

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

您在使用 DocumentConverter 时未注册相应的转换器插件。

启动失败

InvalidOperationException 提及通过 AddPlugin 注册的插件 — 当前的非临时许可证未授予该插件能力。请移除注册或安装授予该能力的许可证。缺失的许可证以及旧版 TRIAL 文件均不授予任何插件能力。

ArgumentException from AddDoconut():

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

这是快速失败的选项验证——请修正有问题的路径。

构建 / 依赖错误

编译错误 CS1705，或在运行时打开文档时出现：

text
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'

您的项目将 System.Text.Json 或 System.Text.Encodings.Web 锁定在低于 Doconut.NET6 声明的 8.0.x 依赖版本。请移除降级并让 NuGet 还原包图（System.Text.Json 8.0.6 与 System.Text.Encodings.Web 8.0.0 在已审计的 26.7.0 包中）。

首次打开演示文件时出现 TypeInitializationException：

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

演示引擎硬性要求 System.Drawing.Common 6.0.0（由包声明）。不要移除或覆盖该依赖——没有它，所有 PPT/PPTX/PPS/POT/ODP 打开都会失败。

输出异常

页面带有水印——应用处于评估状态：未找到许可证文件、临时或订阅期限已过期，或域名无效。检查 IDoconutLicenseService（License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage）——Licensing 页面中的 IDoconutLicenseService 引用提供了现成的端点。

旧版文档渲染为乱码——.NET 6 默认不加载代码页编码。请在启动时一次性添加：

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Linux/Docker 上字体错误或被替换——容器缺少文档所需的字体。请将 FontFolders（在 WordConfig/PptConfig 上）指向已挂载的字体目录。

演示文稿可以打开但在 Linux/macOS 上渲染失败——当前的 PPT/PPTX/PPS/POT/ODP 渲染器需要本地 libgdiplus 并且 System.Drawing.EnableUnixSupport=true。该包提供 System.Drawing.Common 6.0.0，因为这是最后一个支持此开关的版本。

功能在评估环境可用，生产环境却无效

经典的上线惊喜：活跃的临时许可证授予所有能力；而您购买的许可证仅授予已购买的功能。当缺少相应能力时，搜索和批注等功能会消失。已注册的 Converter 或 DICOM 插件在许可证不足的情况下会在 AddDoconut() 时失败。请在部署前使用 IsCapabilityGranted(...) 对比每个启用的功能。

搜索无结果（或结果太少）

  • 对于直接的 PDF，打开时未启用 AllowSearch。Word、Excel 和 PowerPoint 通过其嵌套的 PdfConfig 暴露相同的开关。
  • 内容为扫描件/仅图片，普通搜索没有文本层可匹配。请使用包含文本的来源或保留文本的 PDF 投影。
  • HTML 和 MS Project（MPP）默认不可搜索——将 DefaultRender = false，使其通过带原生文本层的 PDF 投影渲染。Word、Excel、PowerPoint、TXT、Visio、email、EPUB 和 MHT 在其目录默认情况下是可搜索的。
  • objViewer.CanSearch() 在初始化后为 false——解析得到的格式没有标准搜索路径。此判断独立于搜索许可证，请同时确认两者。

仍然卡住？

将问题隔离到最小的 Quick Start 示例应用中；如果在那里也能复现，请携带文档、您的 Program.cs 以及许可证诊断输出联系技术支持。

此页面有帮助吗？