故障排除

诊断常见错误

以下所有信息均为 Doconut 实际输出的文字,按症状组织。找到你的错误并应用修复。

查看器未显示内容

查看器区域为空,浏览器控制台充满针对 /doconut-res/... 的 404 错误
UseDoconutResources() 缺失,或位于 UseDoconut() 之后。它必须在管道中首先出现。

查看器报告 The viewer handler could not be reached (no response).
请求从未得到响应。常见原因是一个以 / 开头的 BasePath:'/doconut' 变为 //doconut/DocImage.axd,即请求指向另一个主机。请去掉前导斜杠写成 BasePath: 'doconut'。

查看器报告 Please make sure your middleware is configured.
页面端点返回了 404:UseDoconut() 未挂载在客户端的 BasePath 所指向的位置。使用 app.Map("/doconut", branch => branch.UseDoconut()) 时,客户端会使用 BasePath: 'doconut'。

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 客户端),或应用重启(产生新会话密钥)。这属于安全层的正常工作——请参阅核心概念 → 会话与安全。拒绝响应是带有状态码 200 的图片,因此仅检查状态码的监控会将其计为页面。

错误图片显示:

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)。插件已注册,但没有许可证再授予其功能——通常是应用启动后已过期的临时许可证。请安装授予该功能的许可证,并在 IDoconutLicenseService 上验证 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>().

您在未注册 Converter 插件的情况下解决了 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=8.0.0.0'

您的项目将 System.Text.Json 或 System.Text.Encodings.Web 锁定在 Doconut.NET8 声明的 8.0.x 依赖以下。删除降级并让 NuGet 恢复包图(System.Text.Json 8.0.5 和 System.Text.Encodings.Web 8.0.0)。

输出显示异常

页面带有水印 — 应用处于评估状态:未找到许可证文件、临时许可证已过期,或域名无效。在有效的临时许可证下,仅插件输出会被加水印。付费许可证订阅日期之后发布的构建不会加水印:打开时会抛出 LicenseException。检查 IDoconutLicenseService(License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage)——授权页面的 IDoconutLicenseService 引用显示了一个现成的端点。

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

字体错误或被替代 — 服务器缺少文档所需的字体。请安装它们,或将 FontFolders(位于 WordConfig/PptConfig)指向包含这些字体的文件夹。在 Linux 上,请参见下文。

图像注释在查看器中显示,但导出时出现“Image blocked”框 — 图像的主机使用私有或回环地址,服务器拒绝获取。请参阅 注释。

Linux

打开任何文档时出现以下错误:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

安装字体配置库:apt-get install -y libfontconfig1(在 RHEL/Fedora 上为 fontconfig)。请参阅 安装。

打开任何文档时出现以下错误:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

应用程序引用了更新的 SkiaSharp,直接或通过其他库。请添加与该 SkiaSharp 相同版本的 SkiaSharp.NativeAssets.Linux。

打开任何文档时出现以下错误:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

宿主机不是受支持的平台。Alpine 及其他基于 musl 的发行版不受支持:请使用基于 Debian 或 Ubuntu 的镜像。

文本比 Windows 上更宽或更窄,或换行方式不同 — 文档的字体未安装,导致 Doconut 使用最接近的已安装字体。安装度量兼容的字体(fonts-liberation 用于 Arial、Times New Roman 和 Courier New;fonts-crosextra-carlito 和 fonts-crosextra-caladea 用于 Calibri 和 Cambria),或将您自己的授权字体复制到 /usr/share/fonts/ 并运行 fc-cache -f。亚洲文字显示为空白方框需要 fonts-noto-cjk。

功能在评估时可用,生产环境中保持静默

经典的上线惊喜:活跃的临时许可证授予所有功能;您购买的许可证仅授予您购买的内容。当缺少相应功能时,搜索和注释捆绑可能会消失。注册的 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 —— 已解析的格式没有标准搜索路径。此判定独立于搜索许可证,请同时验证两者。
  • 页面读取 objViewer.Search(...) 的返回值——计数在其第三个参数(回调函数)中返回。

仍然卡住吗?

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

此页面对您有帮助吗?