企业官网建设流程全解析

如何给扫描 PDF 加上可搜索文本层：OCRmyPDF 快速上手指南

【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF

扫描件有一个让人抓狂的属性：看起来是文档，搜起来是图片。你在 Adobe 阅读器里按 Ctrl+F 找"发票"两个字，半天等不到结果——因为那个 PDF 里根本没有文字，只有一页页像素。手动转图再 OCR，文本位置全乱、重音符号丢失，文件还肿得吓人。

OCRmyPDF（命令行工具名ocrmypdf）就是为这件事做的：一条命令，在原扫描 PDF 上叠一层精确对齐的 OCR 文字。图片不动，文字可搜、可抄、可复制，默认还输出符合 ISO 标准的 PDF/A-2b 存档格式。

快速认识 OCRmyPDF：一条命令补上缺失的文字层

它的工作方式可以概括成三步：用 Ghostscript 把每一页栅格成图像，交给 Tesseract 识别出文字和坐标，再把识别结果以不可见的方式贴回原 PDF 对应位置。默认自动利用全部 CPU 核心并行处理，还顺手做图像压缩，输出文件经常比输入还小（上面的截图里，8 页文档总体积节省了 53.8%）。

和"手动处理"或者自己拼脚本相比，它的差别在于：

一句话：它把"扫描 → 识别 → 对齐 → 存档校验"整条链路的脏活都接管了，你只负责喂文件。

5 分钟装好 OCRmyPDF：Linux、macOS、Windows 最短路径

OCRmyPDF 本身是 Python 程序，但它调用两个外部引擎：Tesseract（识别）和 Ghostscript（PDF 栅格化与存档转换）。三者齐活才算装好。

Python 要求 3.11 及以上（当前发布版为 17.8.1）；Tesseract 最低 4.1.1，Ghostscript 最低 9.54。

装完跑三条命令验证，都能打印版本号就万事大吉：

ocrmypdf --version tesseract --version gs --version

跑通第一条 OCR 命令：最小示例与中文识别命令怎么写

最小可用示例只有三个词：

ocrmypdf 扫描件.pdf 可搜索.pdf

终端会滚动进度条：扫描内容、按页 OCR、PDF/A 转换、图像压缩。结束后提示 "Output file is a PDF/A-2b (as expected)"，打开输出文件复制一段文字，就成了。

中文识别的关键是-l参数，指定语言代码chi_sim：

ocrmypdf -l chi_sim 中文合同.pdf 输出.pdf

如果输入是图片而不是 PDF，需要告诉它拍摄 DPI：

ocrmypdf --image-dpi 300 合同照片.png 合同.pdf

识别质量不佳时，先怀疑语言包或参数，而不是工具本身。

常用参数速查：语言、输出格式、预处理与并发

实用进阶：sidecar 文本、参数组合与批量处理

sidecar 纯文本输出。识别结果除了嵌进 PDF，还可以导出一份 txt，用于建索引库或核对识别质量：

ocrmypdf --sidecar 合同.pdf 输出.pdf # 生成 输出.pdf.txt；参数后加文件名可自定义路径

参数组合思路。档案级处理：-r -d --clean-final加--output-type pdfa，再挂上--title、--author；追求文件最小：--output-type pdf，改动最克制。组合没有标准答案，按"要存档还是要小文件"选一边即可。

批量处理。一个目录几十个文件，shell 循环就够：

for f in *.pdf; do ocrmypdf --skip-text "$f" "ocr_$f" || echo "$f 失败" done

仓库里还带了一个batch.py脚本（misc/batch.py），适合需要按页码范围选择性识别的场景，用法见 docs/batch.md。

常见问题排查：报错信息对照与修复方法

1. "page already has text"

• 现象：提示页面已含文字，直接中止。
• 原因：文件本身已有文本层（或水印），工具默认拒绝重复劳动。
• 解法：确认要重做就加--force-ocr；只想处理扫描件页就--skip-text；想升级旧层用--redo-ocr。

2. "not a valid PDF"

• 现象：输入文件被判为无效。
• 原因：PDF 截断或损坏，多为拷贝未完成。
• 解法：重新传输；或先让 Ghostscript 重写一遍再喂进来。

3. "Tesseract cannot open its config file 'hocr'"

• 现象：Tesseract 静默无输出。
• 原因：手动拼装的 tessdata 目录缺少configs/子目录。
• 解法：从系统包管理器重装 Tesseract，或补全 configs 文件。

4. 语言代码报错

• 现象：提示找不到指定语言。
• 原因：对应的 Tesseract 语言包没装（比如chi_sim需要 tesseract-ocr-chi-sim）。
• 解法：装对应语言包，用tesseract --list-langs确认已生效。

5. 大页面内存不足

• 现象：中途 OOM，任务被杀。
• 原因：高 DPI 大页一次性进内存。
• 解法：调小-j的并发数，或先把大文件分页再处理。

更多错误对照见 docs/errors.md，安装细节见 docs/installation.md。

写在最后

从一条ocrmypdf 输入.pdf 输出.pdf开始，把扫描件变成可搜的文档只要几十秒。语言用-l指定，存档交给默认的 PDF/A，批量交给 shell。遇到报错别慌，先看上面的对照表；想深入，docs/index.md 是从入门到 API 的完整文档入口。工具已经足够成熟，剩下的只是把文件喂给它。

【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF