故障排除

诊断常见错误

以下所有信息均为 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，但未注册 Converter 插件。

启动失败

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=10.0.0.0'

您的项目将 System.Text.Json / System.Text.Encodings.Web 锁定在 10.0.x 以下。请移除降级限制，让 NuGet 恢复 Doconut.NET8 声明的版本。

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）——授权页面的 IDoconutLicenseService 引用提供了现成的端点。

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

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、电子邮件、EPUB 和 MHT 在其目录默认设置下可搜索。
  • 初始化后 objViewer.CanSearch() 为 false —— 解析的格式没有标准搜索路径。此判断独立于搜索许可证，请同时确认两者。

仍然卡住？

请在最小的快速入门示例应用中复现问题；如果仍然出现，请将文档、您的 Program.cs 以及许可证诊断输出一起提交给支持团队。

此页面有帮助吗？