性能调优

优化渲染和内存

Doconut 的资源概况主要受三方面影响：渲染 DPI、缓存内容和会话持续时间。本指南按影响顺序介绍这些调节杠杆。

分辨率 — 最大的杠杆

ImageResolution（25–300 DPI）决定渲染时间和图像大小。大多数格式默认 200 DPI；图像和 PSD 默认 100 DPI。

csharp
// 文档列表预览不需要打印质量
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { ImageResolution = 100 });

将 DPI 减半大约会使每页像素数降低到四分之一——渲染更快、传输更小、缓存占用更少。对放大频繁的使用场景（CAD、工程图纸）保留 250–300 DPI。

对于嵌入大量图像的 PDF，PdfConfig 提供更细的调节：CompressImages + CompressQuality、ResizeImages + ResizeResolution，以及 CompressFast。对于普通图像，ImageConfig.MaxImagePixelSize（默认 3000 像素）限制输出尺寸。

页面缓存 — 内存 vs. 重新渲染

BaseConfig.CachePages（默认 true）在会话期间将每个渲染页面保存在内存中。这是交互式查看的合适默认设置——用户可以前后滚动。当满足以下情况时可关闭：

  • 文档体积庞大且仅查看一次，从头到尾，
  • 并发会话众多会导致缓存页面数量成倍增长，
  • 宁愿为每次查看支付 CPU 开销，也不想占用大量 RAM。
csharp
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { CachePages = false });

在客户端，ViewerConfig.CacheEnabled = true 会在浏览器内存中预加载一个小的移动窗口，包含即将显示的页面图像。这是每次查看的预取缓存，而非持久化的 localStorage。

会话 — 你看不见的内存

每个打开的会话都会保存已解析的文档模型以及（在 CachePages 开启时）其渲染页面，直至滑动的 TimeOut（默认 60 分钟）在自上次请求以来到期。养成以下两种习惯可控制内存占用：

  • 关闭已完成的文档。 viewer.CloseDocument(token) 会立即释放引擎，而不是等待空闲窗口结束。
  • 合理设置超时时间。 用户仅浏览两分钟的预览并不需要一小时的会话：
csharp
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

请记住权衡：超时后小部件会显示 Document session not found. Please re-open document. —— 请选择与实际阅读时长相匹配的超时时间。

针对特定格式的开关

  • Excel：MemoryOptimizationPreference 默认 开启，在渲染超大工作簿时可降低内存占用——保持开启，或在愿意以少量速度提升换取内存时设为 false；SheetNames / PrintArea 可限制渲染范围，仅渲染必要部分。
  • 重定向模式有前置成本：DefaultRender = false 会在打开时将整个文档转换为 PDF。它提供原生文本搜索功能，但在 500 页文档上，打开调用会承担该转换——不要盲目启用。
  • 在 Linux/Docker 上的 Word/PPT：缺少字体会导致缓慢的回退探测和错误的度量；请将 FontFolders 指向包含字体的目录。
  • 在 Linux/macOS 上的演示文稿：PPT/PPTX/PPS/POT/ODP 文件可以打开，但使用当前演示引擎渲染需要原生 libgdiplus 并在运行时开启 System.Drawing.EnableUnixSupport=true。其他格式族使用常规的跨平台渲染路径。

客户端策略

  • LargeDoc = true — 对超大文档采用懒加载策略；页面在用户接近时才加载。
  • AutoLoad = false（默认）— 在实际调用 View(token) 之前不进行渲染。
  • ShowThumbs = false — 对单页或嵌入式预览跳过缩略图生成/请求。
  • 启用 FixedZoom 可避免自由缩放；在映射 C# 的 ViewerConfig 时，为小屏幕调节 FixedZoomPercentMobile（C# 默认 75）。

启动一次，而非每次请求

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance) 应放在 Program.cs 中——每次请求都注册编码是浪费工作；完全忘记注册会导致旧版代码页文档无法解析。

跨节点分摊工作

以上所有内容都是对单节点按需渲染的调优。当单个节点无法承载负载时，下一个杠杆不是调大参数，而是将文档的产物一次性发布到共享存储，让所有节点提供服务。这会改变成本模型：渲染改为每个文档一次，而不是每个会话一次，页面请求变为文件读取。参见 分布式部署。

调优检查清单

  1. 将 ImageResolution 设置为用户体验可接受的最低值。
  2. 交互式查看时保持 CachePages 开启；一次性查看或高并发场景下关闭。
  3. 显式关闭会话；在使用突发的情况下缩短 TimeOut。
  4. 在客户端对大文档使用 LargeDoc 并保持默认的 AutoLoad = false。
  5. 仅在需要带文本的 PDF 投影时才使用 DefaultRender = false。

此页面对您有帮助吗？