企业官网建设流程全解析

5 类报错反向定位：LiteParse 文档解析异常诊断手册

【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse

LiteParse 是一款开源、可在本地高速运行的文档解析器，支持 PDF、DOCX、XLSX、PPTX 与图片输入，可输出 Markdown、JSON 和纯文本。当它出现解析异常——输出空白、满屏乱码、或者直接抛错——多半不是工具"坏了"，而是解析链上某个特定环节失效。本手册不按配置项从头罗列，而是从"报错长什么样"倒推"坏在哪一步"，让你照着一份排查路径走完，几分钟内定位文档解析问题的根源。

上图是一张典型的票据扫描件：页面上只有一张大位图、底下几乎没有可提取文本。解析这类页面却只拿到空字符串时，问题基本就锁定在 OCR 环节——后面会给出确认方法。

先弄清一件事：解析链在哪一步断了

LiteParse 的 Rust 核心按固定顺序处理文档，异常排查的本质就是二分定位：

格式转换 → 文本提取（PDFium）→ 选择性 OCR → 结果合并 → 布局重建 → 输出

各环节对应的源码模块，方便你按需深挖：

记住这个顺序后，下面按症状逐条走。

症状一：解析输出空白怎么办——三步确认页面"本就没有文本"

空白输出最常见的解释不是 bug，而是页面本身是一整张扫描图，而你又没启用 OCR。按以下顺序确认：

1. 跑一次复杂度检测，它逐页给出needs_ocr结论和原因列表：

   lit is-complex document.pdf

2. 看reasons字段：scanned（整页被一张栅格图覆盖）、no-text（无原生文本）、garbled（原生文本解码后是乱码）。任何一页needs_ocr为真，整份文档就算"复杂文档"。

3. 回忆你的命令行：如果带--no-ocr，扫描页必然空白——这是预期行为，不是故障。

判定口径的完整字段说明见 complexity 指南。

症状二：输出乱码——区分"原文就坏"和"语言包没配"

乱码有两大来源，处理方式完全不同：

• 语言包缺失或不匹配：内置 Tesseract 依赖.traineddata语言包，离线环境下常报Error opening data file tessdata/eng.traineddata。解决方式是设置TESSDATA_PREFIX指向语言包目录，或用--tesseract-path一类的参数显式指定；注意内置 Tesseract 认 ISO 639-3 代码（eng、deu），而部分自定义 OCR 服务只认en这类短代码，中文文档尤其要核对。详见 OCR 配置文档 的 Troubleshooting 小节。
• 原生文本本身损坏：字体子集或 cmap 映射损坏时，PDFium 提出来的就是垃圾字符。此时用--extract-text-metadata查看每个文本项的字体与坐标，再配合下面的截图比对，判断是"提取坏了"还是"源文件就这样"。

相关实现在crates/liteparse/src/ocr/tesseract.rs（内置引擎）与crates/liteparse/src/ocr/http_simple.rs（HTTP 服务）。

症状三：硬报错——按错误前缀对号入座

LiteParse 的错误类型集中在crates/liteparse/src/error.rs定义，前缀即分类，看到报错先查这张表：

针对conversion error多补两点：DOCX / XLSX / PPTX 输入必须先经 LibreOffice 转成 PDF；另外警惕"伪装扩展名"——扫描件套个.docx外壳会直接转挂。图片输入则确认格式在 jpg/png/gif/bmp/tiff/webp/svg 之内。

症状四：PDF 扫描件 OCR 失败——它其实是"防静默失败"机制

如果整批页面 OCR 全部失败，LiteParse 会直接抛出OCR failed for all N page(s)而不是返回一份看似完整实则空白的结果——这是刻意设计，宁可响亮地失败。处理顺序：

1. 回症状二，修语言包（TESSDATA_PREFIX）与语言代码；
2. 若走 HTTP OCR（--ocr-server-url接 EasyOCR / PaddleOCR），先用curl -X POST单独打一遍/ocr端点，确认服务本身可用再回头解析；接口契约见 OCR_API_SPEC.md，示例服务在ocr/paddleocr/server.py；
3. 急要结果时临时加--no-ocr拿纯文本，先保住主流程。

症状五：Markdown 结构乱、内容错位——审一遍块分类

Markdown 输出由块分类器生成（标题/段落/表格/列表各归其位），结构怪异通常是某个块被分错。两个手段：

lit parse document.pdf --format json --extract-blocks

• 加--extract-blocks后 JSON 会带上每块的类型与坐标，哪类块越界一目了然；
• 用--target-pages "3-5"、--max-pages把范围压到可疑页，排除大文档干扰。

再做对比实验：--keep-headers-footers看是不是页眉页脚被剥走导致"内容丢失"的错觉，--no-links、--image-mode off分别验证链接和图片处理逻辑。

终极裁决：截图比对

前面所有手段都指向"不确定"时，最直接的办法是让页面自己说话：

lit screenshot document.pdf -o ./screenshots --dpi 150

截图与原文并排看，"提取坏了"还是"原文就这样"立刻见分晓。

收束：一条排查路径走完全程

🔍 按症状对号：空白 → 症状一；乱码 → 症状二；报错 → 症状三/四；结构乱 → 症状五；都怀疑 → 截图裁决。

1. lit is-complex定页面类型（扫描 / 无文本 / 乱码）；
2. 核对 OCR 三要素：语言包路径、语言代码、服务器连通性；
3. --target-pages+--extract-blocks缩小战线、审块分类；
4. lit screenshot截图，与原文终审。

配合 CLI 完整参考 与 library-usage 指南，绝大多数解析异常都能在这条路径上定位收口。

【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse