如何用 OCRmyPDF 的 --sidecar 同时产出 OCR 文本文件和 PDF

处理扫描 PDF 时，你往往需要两份产物：一份带 OCR 文本层、可以搜索的 PDF，以及一份纯文本文件，用于建索引、归档或喂给下游程序。OCRmyPDF 的 --sidecar 选项可以在同一次 OCR 运行中同时生成这两份文件，而不必再跑一遍文本提取工具。本文介绍如何用它完成“一次输入，PDF + 文本文件双输出”，以及如何判断结果是否符合预期。

准备条件

按 安装文档 完成 OCRmyPDF 的安装。以 Debian/Ubuntu 为例：

apt install ocrmypdf

pip 无法提供的外部依赖必须用系统包管理器满足，最低要求见 Requirements for pip and HEAD install：

• Python 3.11 或更新（推荐 3.12+）；
• Tesseract 4.1.1 或更新；
• Ghostscript 9.54+ 或 pypdfium2（Python 包）二选一，用于 PDF 栅格化；
• Ghostscript 9.54+ 或 verapdf 二选一，用于 PDF/A 输出。

其他常见安装方式（Homebrew、Fedora dnf、Docker 等）在 Installing OCRmyPDF 中均有说明。用 ocrmypdf --version 确认安装成功。

一次运行产出 PDF 和文本文件

主路径命令如下，input.pdf、output.txt、output.pdf 替换为你自己的文件路径：

ocrmypdf --sidecar output.txt input.pdf output.pdf

命令成功后会得到两个文件：带 OCR 文本层的 output.pdf，以及名为 output.txt 的 sidecar 文本文件，里面是 OCRmyPDF 从图像中识别出的文本（来源：docs/cookbook.md）。

--sidecar 的文件名参数可以省略，此时 sidecar 文件名为 {output_file}.txt，例如输出 output.pdf 对应 output.pdf.txt。注意省略 FILE 时，下一个参数不能是输入 PDF 的文件名（CLI 帮助中的原始描述）。

两个文件不能重名：sidecar 文件必须与输入文件、输出文件都不同，否则报错 --sidecar file must be different from the input and output files（见 校验逻辑）。

变体：只预览文本，或只要文本不要 PDF

以下两个用法来自 docs/cookbook.md 与 docs/advanced.md 的说明，按需选用：

只把 sidecar 写到 stdout，快速预览 OCR 质量：把 --sidecar 的文件名设为 -。限制是输出文件与 sidecar 不能同时使用 stdout；如果输出文件是 stdout（即 -），必须给 --sidecar 一个真实文件名，否则报错 --sidecar filename needed when output file is stdout.：

ocrmypdf --sidecar - input.pdf -

只要文本文件，不生成输出 PDF：使用 --output-type none（该选项自 v12.6.0 提供，用于“只需要 sidecar 文件”的应用场景）。此时输出文件名设为 -，即不产生 PDF 文件：

ocrmypdf --output-type none --sidecar output.txt input.pdf -

--output-type 的完整取值（auto/pdfa/pdf/none 等）见 docs/advanced.md 的 PDF/A output modes 表格，其中 none 一栏的说明就是 “No output file (useful with --sidecar)”。

结果验证与内容边界

命令正常退出后，确认 output.pdf 和 output.txt 两个文件都已生成，再查看文本内容是否符合预期：

cat output.txt

需要理解 sidecar 内容的一个关键边界（来自 cookbook 的说明）：

• sidecar 里只有 OCRmyPDF 做 OCR 时识别出的文本。文档中原本就带文本层的那些页面，其原有文本不会出现在 sidecar 中；
• 如果使用了 --pages，只有实际执行了 OCR 的那些页会包含在 sidecar 中；
• 因 --skip-big、--tesseract-timeout 等原因被跳过的页，不会出现在 sidecar 中。

如果你的目标是“抽出 PDF 里的全部文字（无论来自 OCR 还是原有文本层）”，文档建议改用 Poppler 的 pdftotext 或 pdfgrep 这类工具，而不是依赖 sidecar。

另外，OCRmyPDF 默认假设文档是英文；文档不是英文时必须用 -l LANG 指定语言（例如 ocrmypdf -l fra --sidecar output.txt input.pdf output.pdf），且所有指定语言的语言包都必须已安装，否则 OCR 质量会很差。Tesseract 本身没有自动检测语言的能力（见 docs/cookbook.md）。

参考资料

• docs/cookbook.md：sidecar 命令示例与内容边界说明；
• docs/advanced.md：--output-type 各取值的行为；
• src/ocrmypdf/_validation.py：--sidecar 参数校验规则；
• docs/installation.md：安装方式与外部依赖版本要求。