故障排除
诊断常见错误
以下所有信息均为 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,内容如下:
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 应用已默认注册)。
页面区域的错误图片显示:
You Are Not Authorized To View This Page.该令牌是由不同的浏览器会话打开的。常见原因包括:会话 cookie 未随页面请求发送(跨域设置、SameSite 策略、未携带 cookie 的 API 客户端),或应用重启(产生新会话密钥)。这正是安全层按设计工作的表现——参见核心概念 → 会话与安全。拒绝响应是带有状态码 200 的图片,因此仅检查状态码的监控会将其计为页面。
错误图片显示:
Document session not found. Please re-open document.令牌已过期(滑动窗口,默认 60 分钟 — DocOptions.TimeOut)或会话已关闭。请重新打开文档以获取新的令牌。
服务器正常但页面表现异常 — 且无任何错误
以下是迁移应用后首先需要怀疑的故障模式。这三种情况都会让服务器保持正常运行,文档渲染正确,但浏览器控制台不报任何错误。
永不停止的加载指示器。 你的查看器回调被声明为以容器 id 命名的全局函数 —— ctlDoc_OnViewerReady() 及其相关函数。之前的查看器会查找这些名称;而此版本不会。用于隐藏指示器的处理程序根本未被调用。请改为将函数作为选项传入:
function ctlDoc_OnViewerBusy() { /* 显示忙碌指示器 */ }
function ctlDoc_OnViewerReady() { /* 隐藏它 */ }
function ctlDoc_Copy(text) { /* 使用复制的文本 */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* 报告进度 */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... 您现有的选项 ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});指示器后面的文档本身没有问题。完整的选项列表请参见 ViewerConfig。
缺少查看器图标或外壳,其他页面正常。 ResPath 为空或指向应用根目录——在之前的库中是正确的,但在此处错误。它必须指明 UseDoconutResources() 挂载的前缀:
ResPath: 'doconut-res/images' // 或 '<your ResourcesPath>/images'从共享存储提供服务时后续页面出现碎片。 正在写入的页面会返回 202 Accepted。没有 retryOn409: true 的客户端会将其视为加载失败的图片。参见 Distributed Deployments.
打开文档失败
LicenseException 带有拒绝信息 — 找到了许可证文件但被拒绝(签名无效、被篡改、列入黑名单,或构建超出许可证的版本/更新窗口)。此状态会阻止打开(快速失败),而不是降级为水印;请阅读 License.RejectionMessage 了解原因。
LicenseException:
This document type requires the 'Dicom' plugin license.该扩展仅由插件处理(此处为 DICOM)。插件已注册,但没有许可证再授予其功能——通常是已在应用启动后过期的临时许可证。安装授予该功能的许可证并在 IDoconutLicenseService 上验证 IsCapabilityGranted(LicenseCapability.Dicom)。缺少或不足的非临时授权通常会在 AddDoconut() 时更早失败。
FormatNotSupportedException:
Document format '<extension>' is not supported.没有任何查看器(内置、插件或自定义)声明支持该扩展。检查受支持格式列表;对于自定义格式,DoconutOptions.RegisterViewer 可以添加一个。
InvalidDataException — 文件内容损坏或与其扩展名不匹配(例如被重命名的文件)。在打开之前请验证上传的文件。
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().您在未注册 Converter 插件的情况下解决了 DocumentConverter。
启动失败
InvalidOperationException 提及通过 AddPlugin 注册的插件 — 当前的非临时许可证未授予该插件功能。移除注册或安装授予该功能的许可证。缺少许可证以及旧版 TRIAL 文件均不授予插件功能。
ArgumentException 来自 AddDoconut():
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 目标为
netstandard2.1,因此 NuGet 拒绝 .NET Framework 项目。这不是可解决的
还原错误:.NET Framework 无法使用 netstandard2.1。请改用
Doconut.NETFramework 软件包。
编译器错误 CS1705,或在运行时打开文档时出现:
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'您的项目将 System.Text.Json 或 System.Text.Encodings.Web 锁定在 9.0.x 以下,
而这些是由 Doconut.NETStandard 声明的依赖。移除降级并让 NuGet 还原
软件包图(System.Text.Json 9.0.0 和 System.Text.Encodings.Web 9.0.0 如软件包所声明)。
在升级软件包后立即出现大量编译错误 — 这是预期的。
26.8.0 与 26.7.0 的 API 表面不同,非兼容更新。大多数
错误是已移动到根 Doconut 命名空间的 using 行;请通过
Migrate to .NET Standard 2.1 逐步迁移,而不是逐个修补。
TypeInitializationException 在第一个演示文件上:
Could not load ... System.Drawing.Common, Version=6.0.0.0演示引擎硬性要求 System.Drawing.Common 6.0.0(由软件包声明)。不要移除或覆盖该依赖——否则所有 PPT/PPTX/PPS/POT/ODP 打开都会失败。
输出异常
页面带有水印 — 应用处于评估状态:未找到许可证文件、临时许可证已过期,或域名无效。在有效的临时许可证下,仅插件输出会被加水印。付费许可证订阅日期之后发布的构建不会加水印:打开时会抛出 LicenseException。检查 IDoconutLicenseService(License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage)——授权页面的 IDoconutLicenseService 引用显示了现成的端点。
旧版文档呈现乱码 — 默认未加载代码页编码。请在启动时添加一次:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);字体错误或被替换 — 服务器缺少文档所需的字体。请安装这些字体,或将 FontFolders(位于 WordConfig/PptConfig)指向包含这些字体的文件夹。
图像批注在查看器中显示,但导出时出现 “Image blocked” 框 — 图像的主机使用私有或回环地址,服务器拒绝获取。请参阅 批注。
功能在评估时可用,生产环境中保持沉默
经典的上线惊喜:活跃的临时许可证授予所有功能;您购买的许可证仅授予您所购买的内容。当缺少相应功能时,搜索和注释捆绑可能会消失。已注册的转换器或 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,以及许可证诊断输出联系支持。
此页面对您有帮助吗?