故障排除

诊断常见错误

以下所有信息均为 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()。会话状态同样需要缓存：在最小 API 应用中添加 builder.Services.AddDistributedMemoryCache()，否则应用启动时会出现 Unable to resolve service for type 'IDistributedCache'（MVC 与 Razor Pages 应用已默认注册）。

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

text
You Are Not Authorized To View This Page.

该令牌是由不同的浏览器会话打开的。常见原因包括：会话 Cookie 未随页面请求发送（跨域设置、SameSite 策略、没有 Cookie Jar 的 API 客户端），或应用重新启动导致会话密钥更换。这是安全层的正常工作方式——请参阅 Core Concepts → Sessions & Security。

页面显示错误图片，内容为：

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 来自 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——解析得到的格式没有标准搜索路径。此结果独立于 Search 许可证，请同时确认两者。

仍然卡住？

将问题在最小的快速入门示例应用中复现；如果在那里也会出现，同步提供文档、你的 Program.cs 以及许可证诊断输出，以便联系支持人员。

此页面对您有帮助吗？