故障排除

诊断常见错误

以下所有信息均为 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()。会话状态还需要缓存：在 minimal-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 的 API 客户端），或应用重启导致会话密钥更换。这是安全层的正常工作方式——请参阅核心概念 → 会话与安全。

错误图片显示:

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

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

服务器正常但页面异常 — 且无任何错误

以下是迁移应用后首先需要怀疑的故障模式。三种情况都会让服务器正常运行、文档渲染正确，但浏览器控制台没有任何报错。

永不停止的加载动画。 你的查看器回调被声明为全局函数，名称基于容器 id —— 如 ctlDoc_OnViewerReady() 等。之前的查看器会查找这些函数；而当前的查看器没有。用于隐藏加载动画的处理程序根本未被调用。请改为将函数作为选项传入：

javascript
objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

加载动画背后的文档本身是正常的。完整的选项列表请参阅 查看器配置。

缺少查看器图标或外观，其他页面正常。 ResPath 为空或指向应用根目录 —— 在之前的库中是正确的，但在这里不对。它必须指定 UseDoconutResources() 挂载的前缀：

javascript
ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

从共享存储提供服务时后续页面出现碎片。 正在写入的页面会返回 202 Accepted。未设置 retryOn409: true 的客户端会将其视为图片加载失败。请参阅 分布式部署。

打开文档失败

带有拒绝信息的 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 mentioning a plugin registered via 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.

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

构建 / 依赖错误

包根本无法安装 — Doconut.NETStandard 26.8.0 目标为 netstandard2.1，导致 NuGet 拒绝 .NET Framework 项目。这不是可恢复的还原错误：.NET Framework 无法使用 netstandard2.1。请改用 Doconut.NETFramework 包。

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

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

你的项目将 System.Text.Json 或 System.Text.Encodings.Web 锁定在低于 Doconut.NETStandard 声明的 9.0.x 依赖版本。移除降级并让 NuGet 还原包图（System.Text.Json 9.0.0 与 System.Text.Encodings.Web 9.0.0 在已审计的 26.8.0 包中）。

升级包后立即出现大量编译错误 — 这是预期行为。26.8.0 与 26.7.0 的 API 表面不同，非兼容更新。大多数错误来自已迁移到根 Doconut 命名空间的 using 行；请参考 迁移到 .NET Standard 2.1 而不是逐个修补。

在第一个演示文件上出现 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 引用显示了现成的端点。

旧版文档渲染为乱码文本 — 默认未加载代码页编码。请在启动时添加一次：

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

仍然卡住了吗？

将问题隔离到最小的快速入门应用中；如果在那里复现，请携带文档、您的 Program.cs 以及许可证诊断输出联系支持。

此页面对您有帮助吗？