LiteParse 文档解析异常排查指南空白、乱码、结构错乱四大症状快速对照清单【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparseLiteParse 是一款本地运行、免费开源的文档解析工具支持 PDF、DOCX、XLSX、PPTX 与图片输入一键输出 Markdown、JSON、纯文本并内置 OCR 识别扫描件。刚装完就遇到解析异常不用慌按症状对号入座即可下面每条都按“现象 → 可能原因 → 处理办法 → 验证方式”的固定套路给出。结果空白或缺内容先确认是不是扫描页输出只剩几个字甚至全空时先确认它是不是扫描页——整页其实是一张拍出来的图片文字层要么没有、要么是噪音文字只能靠 OCR 出来。页面是扫描图OCR 没生效。运行工具自带的页面类型检测逐页给出判定与原因scanned整页图片、no-text无可提取文本、garbled原生文本解码成乱码。判定为needs_ocr时说明该页必须走识别链路。lit is-complex document.pdf验证被标scanned的页若解析时带了--no-ocr空白是必然的去掉该参数重跑对比。这张票据就是典型全靠 OCR 的页面解析出空文本时可基本锁定 OCR 环节 。Tesseract 语言包缺失。离线环境下.traineddata没有下载会报Error opening data file tessdata/eng.traineddata。设置环境变量TESSDATA_PREFIX指向语言数据目录或加参数--tessdata-path急着要结果就先--no-ocr拿纯文本。验证重跑不再报这个错。语言代码与服务端不匹配。内置 Tesseract 用 ISO 639-3 代码eng、deu、jpn自建的 HTTP OCR 服务常只认en而--ocr-language默认值就是eng服务端收到不认的代码可能报错也可能悄悄返回空结果。换成服务端认的代码即可官方 PaddleOCR / EasyOCR 示例服务会自动做eng→en映射。验证先单独测一下/ocr端点通了再谈解析。报OCR failed for all N page(s)。这是防静默失败的设计所有页面都失败就报错而不是交一份看似完整实则空白的结果。按第 2、3 条修或--no-ocr先把原生文本拿到手。乱码、文字不对检查语言选择与文本元数据输出有字但读不通或与原文明显不符多为语言选错或原生文本层本身就有问题。OCR 语言与文档不符。默认eng去认中文或外语必然错。换成对应语言代码并确认对应的.traineddata就位。验证重跑同一页人工读一遍错字明显减少才算修好。原生文本层本身乱。文字被画成矢量轮廓、或字体用了私有编码时不经过 OCR 提取出来也是乱码。重跑 is-complex 看garbled、vector-text等原因lit parse document.pdf --format json --extract-text-metadata它会输出每个文本项的字体高度、字重、颜色、旋转对照原文就能定位是哪部分字出了问题。源图分辨率太低。扫描件不清晰识别错字难免。调高--dpi重渲染再走一次提取提高渲染精度能救回一部分识别错误截图本身发糊就是源文件的问题。结构错乱、页眉页脚混入查输出参数与块分类顺序乱了、表格散了、页眉逐行重复Markdown 看起来像一坨。页眉页脚误删或想保留。默认会剥离页面上下区域跨页重复出现的行正文内容可能被误伤。加--keep-headers-footers全保留再确认。验证对比加与不加该参数的两份输出。块分类分错。Markdown 由块分类器生成表格被当段落、列表项散掉就是分类问题。每个块都带类型与包围盒坐标顺序即阅读顺序用块视图直接看lit parse document.pdf --format json --extract-blocks验证在blocks里按坐标定位可疑区域核对块类型标题/段落/表格/列表是否合理。大文档难定位。用--target-pages 3-5、--max-pages把范围缩到可疑页--no-links、--image-mode off可以单独开关做对比实验。验证单页结构正常后再看跨页交互。启动即报错、转换失败环境依赖清单命令一启动就报错进不到解析环节多半是环境问题。报conversion error转换组件缺失。DOCX / XLSX / PPTX 都依赖 LibreOffice 先转成 PDF未安装时工具会直接提示缺少哪个依赖。装上它Windows 还要把其program目录加入 PATH 并重启终端。验证在终端单独跑一次转换。扩展名是假的。文件其实是扫描图却叫.docx转换必然失败。用文件管理器看一眼文件类型、或换个工具打开确认改回真实格式再解析jpg/png/tiff/webp 等图片原生支持无需转换。加密文档没给密码。PDF 报错常因缺密码加--password重试。按前缀归类。错误类型集中在 error.rsPDF error文件损坏、密码、IO error路径、权限、conversion errorLibreOffice、OCR failed语言包、服务、invalid config参数组合按对应症状处理。截图比对原文与五步排查顺序分不清是“提取坏了”还是“原文就这样”人工比对是最快的裁决方式lit screenshot document.pdf -o ./screenshots --dpi 150截图有字、结果没有是提取或 OCR 问题截图也糊问题在源文件。各判定原因的含义见 OCR 配置指南参数细节见 CLI 参考。排查顺序五步走完 lit is-complex判页面类型scanned/no-text/garbled核 OCR 配置语言代码、TESSDATA_PREFIX、--ocr-server-url--target-pages缩范围--extract-blocks看块分类lit screenshot生成截图与原文比对按错误前缀归类PDF error/IO error/conversion error/OCR failed/invalid config五步走完多数解析异常都能定位到具体环节。【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考