企业官网建设流程全解析

5 分钟定位 LiteParse 解析异常：缺字、乱码、整页空白怎么办

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

输出缺了半页内容、报错信息却不说原因？别慌。LiteParse 是一款在本地高速运行的文档解析工具，把 PDF、DOCX、图片转成 Markdown、JSON 或纯文本。照下面的步骤走一遍，90% 的 LiteParse 解析异常能在 5 分钟内定位到根源。

排查前自检：先排除这 4 个非 bug 问题

1. 工具装好了吗：先确认命令行能跑通

   lit --version

   如果提示命令不存在，说明安装没完成，后面的一切排查都白做。

2. 文件扩展名是真的吗：伪装成.docx的扫描件会直接转换失败，用文件管理器确认实际格式。
3. 加密文件传密码了吗：加密 PDF 报PDF error时，第一反应应该是加--password。
4. 参数拼写对不对：--no-ocr、--target-pages这类开关拼错会被当成无效配置，直接报invalid config。

症状一：怎么判断“整页空白”其实是扫描件

现象：输出里某页没有字，或者只有零星几个字符；is-complex命令对该页输出needs_ocr: true，原因写着scanned或no-text。

排查顺序：

1. 先运行复杂度检测，让它逐页告诉你哪些页需要 OCR（光学字符识别，即从图片里认字）

   lit is-complex document.pdf

2. 如果某页被标为scanned，而你又用了--no-ocr，那“整页空白”是必然的——页面本身就是一张图片，关掉 OCR 等于没有任何东西可提取。
3. 去掉--no-ocr重跑一次。如果此时报 OCR 相关错误，转去下面“症状二”。

下图是一张典型的票据扫描件，解析这类页面却只得到空文本时，基本可以锁定问题出在 OCR 环节：

相关入口：复杂度判定文档，这是is-complex输出里每个判定原因（scanned、no-text、garbled）的完整解释。

症状二：LiteParse OCR 报错怎么解决

现象：出现以下任一类报错：

• Error opening data file tessdata/eng.traineddata—— 这说明 Tesseract 语言包（认字模型文件）没下载下来，离线环境最常见；
• 语言代码不匹配 —— 内置 Tesseract 用 ISO 639-3 三字母代码（eng、deu），你传了en就会失败；
• OCR failed for all N page(s)—— 这是防静默失败设计：所有页 OCR 都挂掉时宁可报错，也不给你一份看似完整实则空白的结果。

排查顺序：

1. 报错提到traineddata时，把语言包目录指给它：

   lit parse document.pdf --tessdata-path /path/to/tessdata

   或者设置环境变量TESSDATA_PREFIX，二选一即可。

2. 检查--ocr-language的值是不是三字母代码，中文文档记得换成对应语言包，别复用eng。
3. 如果走的是--ocr-server-url接入的自定义服务器（EasyOCR、PaddleOCR），先用curl -X POST单独测通它的/ocr端点，再回来谈解析——网络不通时解析端只会给你干等。

相关入口：OCR 指南 的 Troubleshooting 小节，这里列了语言包缺失、离线缓存等场景的完整处理步骤；语言代码的映射逻辑在 ocr/tesseract.rs。

症状三：“乱码”和 Markdown 结构怪异

现象：输出有字但读不通（“乱码”），或标题、段落、表格的位置明显不对。

排查顺序：

1. 加--extract-blocks重跑，让 JSON 输出带上每个块（标题/段落/表格）的坐标，直接看是哪一类块被分错了

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

2. 开--keep-headers-footers保留页眉页脚对比一次，排除“内容其实还在、只是被你当丢了”的误判。
3. 仍不确定是提取坏了还是原文就这样时，用--extract-text-metadata查看每个文本项的字体与位置，乱码常来自某个字体的字符映射错位。

相关入口：error.rs 集中定义了所有错误前缀，看到PDF error、OCR failed、invalid config这些字样就能秒判故障属于哪一层。

症状四：conversion error 说明什么

现象：输入 DOCX / XLSX / PPTX 时报conversion error。这说明 LiteParse 依赖 LibreOffice 先把 Office 文档转成 PDF，而转换这一步没走通。

排查顺序：

1. 确认 LibreOffice 已安装且命令行能调用它；Windows 上还要把它的program目录加进 PATH。
2. 确认文件扩展名是真实的，套错后缀的扫描件到不了转换环节就会失败。
3. 图片输入只支持 jpg / png / gif / bmp / tiff / webp / svg，其他格式换一种再试。

相关入口：conversion.rs，这是 Office 格式转 PDF 的完整实现，报错信息基本都从它冒出来。

通用隔离三板斧

1. 把输入缩到最小：只解析可疑的那几页，排除大文档干扰

   lit parse document.pdf --target-pages "3-5"

2. 开关做对照实验：同一份文件换一组开关跑两次，差异处就是答案

   lit parse document.pdf --no-ocr

3. 生成中间产物比对：把页面截图存下来，肉眼核对原文长什么样

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

现象速查表

按“自检 → 对症状 → 三板斧”这个顺序走，绝大多数 LiteParse 报错都能归位。完整的参数说明见 CLI 参考文档，那里列了本文用到的每个开关的细节。

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