扫描件加文本层：OCRmyPDF 离线使用完整指南

扫描件加文本层：OCRmyPDF 离线使用完整指南

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

一份扫描合同塞进 PDF 阅读器，Ctrl+F 毫无反应——它只是一张图片。OCRmyPDF 给这类文件补一层隐形文字，识别和合成都发生在本机：Tesseract 读字、本地重建文本层，全程不需要联网。

它解决什么问题

扫描件里的文字只是像素，搜索、复制、粘贴都用不上。OCRmyPDF 跑完后，输出 PDF 保持原样，底下多一层看不见的文字，Ctrl+F 就能搜到内容，也能选中复制。对存档场景，它还能顺手把文件转成 PDF/A，长期不跑版。

准备清单：版本与依赖

离线安装前，先把这张清单上的东西在一台有网的机器上备齐，再整体搬到离线环境。

注意 Python 依赖（pikepdf、Pillow、fpdf2 等）pip 无法离线自举，需要在有网机器上执行pip download ocrmypdf -d ./pkgs把 wheel 一并备下，随目录拷贝过去。

最小安装路径：Ubuntu 三条命令

以 Ubuntu 22.04/24.04 为例，系统源里就有全部依赖，一条命令装齐：

apt update && apt install ocrmypdf tesseract-ocr-chi-sim fonts-noto

装完用版本命令自检，它会打印 ocrmypdf、Tesseract、Ghostscript 各自的版本，缺什么一目了然：

ocrmypdf --version

其他发行版两行带过：Debian 命令相同；Fedora 用dnf install ocrmypdf tesseract-osd。macOS 走brew install ocrmypdf，默认带英语语言包，中文另装brew install tesseract-lang。Windows 用 winget 装 Python 和 Tesseract，Ghostscript 需手动下载，最后pip install提前备好的 wheel。更细的平台步骤见 docs/installation.md。

首次运行：一张扫描件变成可搜索 PDF

仓库自带一张打字机扫描件，适合做第一次验证。在仓库根目录执行：

输入：一份没有文字层的黑白扫描件（仓库内 tests/resources/typewriter.png）

ocrmypdf --language eng tests/resources/typewriter.png recipe.pdf

--language eng指定按英语识别（默认就是 eng，写出来是为了强调离线环境要确认语言包在场）。跑完后recipe.pdf里既有原图，也有文字层，用任何阅读器打开都能搜索原文。

执行过程大致是这样的——扫描、OCR、PDF/A 转换、优化各占一条进度条，最后给出压缩比：

一次完整的离线处理：8 页并行 OCR，输出 PDF/A-2b，文件缩小 53.8%

参数速查表：8 个最常用的开关

实战案例：中文合同转 PDF/A 归档

扫描仪吐出一沓 60 页的中文合同，其中夹着几页已经带文字的附件。目标：可搜索 + 长期归档格式 + 体积压下来：

ocrmypdf --language chi_sim --output-type pdfa --optimize 3 --skip-text 合同扫描.pdf 合同_归档.pdf

--skip-text是关键：带文字的附件页直接放行，只对纯图像页做 OCR，既省时间又不会把已有文字打坏。--optimize 3会同时启用 pngquant 和 JBIG2（装了才生效），扫描件体积通常能压掉一半以上。跑完在阅读器里搜"违约金"，能直接定位到对应段落。

排障：现象 → 原因 → 解决

更多报错的来龙去脉在 docs/errors.md。

提效方向：批量与目录监控

一次性几十个文件，shell 循环就够：

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

带--skip-text后，已处理过的文件会安全跳过，循环可以重复执行。需要递归子目录、自动归档原件、写日志的话，直接改 misc/batch.py——它把"跳过加密件、跳过签名件、跳过已 OCR 件"的异常分支都处理好了，改两个目录变量就能投产。

更高一级的自动化是目录监控：装一下 watcher 依赖（uv sync --extra watcher），运行python misc/watcher.py --help看参数，把监控目录指到扫描仪的输出盘，之后新落盘的 PDF 会被自动 OCR 进输出目录，按月建文件夹归档，人不碰鼠标。

结语

完整参数清单见 docs/advanced.md，安装细节与 Docker 方案在 docs/installation.md。核心代码在 src/ocrmypdf/ 目录，OCR 管线的每一步都能拆开看。

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