anydoc 错误处理与限制 - ConvertError 排查
错误处理限制
先明确一点：anydoc 的错误语义很干净——所有语言共用一套 ConvertError，映射一致，排查思路也一致。这篇把六种错误和已知限制一次讲清。
六种错误，一张表
| 错误 | 含义 | 常见触发 | 排查思路 |
|---|---|---|---|
Unsupported | 不支持的格式 | 扫描版 PDF、冷门专有格式 | 确认文件真实格式；扫描 PDF 走 OCR 方案 |
Malformed | 文件损坏或内容非法 | 文件被截断、改名骗扩展名 | 用官方软件重新保存 |
Encrypted | 文档加密 | 带密码保护的 docx/xlsx/pdf | 先解密再转 |
ResourceLimit | 超过安全限制 | 超大文件、zip 炸弹 | 拆分文档；确认来源可信 |
MissingPart | 压缩包关键部件缺失 | OOXML 文件不完整 | 重新导出/下载完整文件 |
Io | 底层 I/O 错误 | 路径不存在、无权限、文件占用 | 检查路径、权限、进程占用 |
各语言怎么拿到错误
// Node.js
catch (e) { e.code } // 'Unsupported' 等# Python
except anydoc.UnsupportedError: # 异常子类// Rust
match err {
anydoc::ConvertError::Unsupported => ...
}已知限制（重要）
扫描版 PDF 不支持
纯图片/扫描版 PDF 需要 OCR，anydoc 会返回 Unsupported。这不是 bug，是设计边界——anydoc 只做文本型 PDF 的本地转换（通过 pdf-inspector）。
替代方案：
- 需要 OCR 时，用 Firecrawl Parse——它在 anydoc 同一转换链路上叠加了 OCR
- 或者先用本地 OCR 工具（tesseract 等）把 PDF 转成文本再喂给 anydoc
页眉页脚页码被排除
所有格式统一剔除页眉、页脚、页码、日期/时间占位符。这是为了给 LLM 干净的输入，目前不支持开关。
视觉细节不保留
输出是 Markdown 不是 PDF 快照。复杂排版（文本框绝对定位、艺术字、精密图表）会降级为可读文本，信息完整度靠基准测试的 87 分保证，但不保证像素级还原。
超大文件有上限
解压、嵌套深度、节点数有固定安全限制。几百 MB 的怪物文件可能触发 ResourceLimit——先拆再转。
高频问题
转出来是空的 / 只有少量内容？
先确认文件不是扫描版；再用官方软件打开确认文件本身没损坏；最后检查是不是加密文档。
为什么我的表格没有合并单元格效果？
合并单元格会转成 Markdown 表格的规整形式（基准里"表格"维度 78 分），但 Markdown 本身表达不了合并——内容都在，视觉合并丢失。
图片为什么变成文字了？
图片默认以 alt 文本呈现，原始字节保留在文档模型上（toDocument 层）。要图片落盘，从模型资源节点取字节写入文件即可。
转换很慢？
正常单份文档中位数 < 5ms。如果很慢，大概率是文件超大或来源异常。也检查是不是在循环里重复初始化（WASM 场景记得只 init() 一次）。
怎么确认没转错？
抽查三样：标题层级（# 数量）、表格规整度、代码块/列表结构。批量转换建议对关键文档做一次快照对比。
一句话
错误六种、边界三条（扫描 PDF、页眉页脚剔除、视觉不保真）——把这些记住，anydoc 的坑基本就踩不完了。