OCRmyPDF 离线 OCR 完整指南：断网也能给扫描 PDF 加可搜索文本层
【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF
OCRmyPDF 是一个给扫描 PDF 加 OCR 文本层的命令行工具，加完之后文字可以框选、复制、搜索。它的识别、排版、压缩全部在本地机器上完成，只要备料做足，离线、断网、内网隔离环境下照样完整可用——真正需要联网的只有"补给"动作：下载安装包和语言包。所以整条思路就一句话：下载的事交给联网机器，干活的事全放在断网机器上。
1. 断网前划清边界：OCRmyPDF 离线能做和不能做什么
先把范围说清楚，避免在离线机上白忙活：
| 场景 | 断网环境下 | 说明 |
|---|---|---|
| 对 PDF / 图片执行 OCR、生成带文本层的输出 | ✅ 完全支持 | 识别、排版、压缩全部在本地完成 |
| 识别中文、日文等其他语言 | ✅ 支持 | 前提：对应的.traineddata语言包已随安装包一起带过去 |
输出 PDF/A、--clean清洗、--optimize压缩 | ✅ 支持 | 分别依赖本地程序 unpaper、Ghostscript、pngquant，备料时装好即可 |
| 下载新语言包 | ❌ 需要网络 | 在有网机器上下载，再拷入离线机 |
| 升级 OCRmyPDF 及依赖 | ❌ 需要网络 | 离线机沿用已部署的版本即可 |
一句话：离线机完全自给自足，它只负责"干活"，不负责"进货"。
2. 趁联网把料一次下齐：包、wheel 和语言包一个都不能少
备料的核心是"一次下齐"。下面这份清单的版本要求均来自项目安装文档，逐行对照打钩：
| 组件 | 用途 | 获取方式 |
|---|---|---|
| Python 3.11 或更高（推荐 3.12+） | 运行 OCRmyPDF | 官方安装程序或发行版包 |
| Tesseract 4.1.1 或更高 | OCR 识别引擎 | 发行版包管理器 / 官方安装程序 |
| Ghostscript 9.54+ 或 pypdfium2 | 页面栅格化、PDF/A 转换 | 系统包；pypdfium2 随 wheel 一起下载 |
| fpdf2、uharfbuzz 等 Python 依赖 | 渲染文本层 | 在有网机器执行pip download ocrmypdf -d ./wheels，一次带齐全部 wheel |
.traineddata语言包 | 各语言的识别数据 | 从 tessdata 源下载，与安装包一起拷贝 |
| fonts-noto 字体包（推荐） | 正确渲染多语种文字 | apt install fonts-noto（Debian/Ubuntu） |
| unpaper / pngquant / jbig2enc（可选） | 支撑--clean、--optimize 2/3、单色图压缩 | 发行版包管理器 |
⚠️ 最容易被漏掉的是.traineddata：它不随 Tesseract 默认全量安装。如果离线后要识别中文，务必把chi_sim.traineddata放进待拷贝清单，并直接放进目标机器的tessdata目录。
3. 离线机上安装：Linux、Windows、macOS 三条路径
三个系统思路一致：把在线渠道能拿到的东西全部落成"文件"，拷到离线机本地安装，只是渠道不同。
Linux：包文件预缓存，本地安装
在有网机上用发行版自带的下载命令把依赖全量缓存，拷贝后本地安装：
apt-get download ocrmypdf ghostscript tesseract-ocr python3 python3-pip dpkg -i *.debFedora、Alpine 同理，换用dnf download/apk缓存即可（在线参考命令：apt install ocrmypdf，Fedora 为dnf install ocrmypdf tesseract-osd）。部分发行版默认不带 JBIG2 编码器，离线机没有它也能跑，只是输出文件会大一些。
Windows：安装器 + 本地 wheel 收尾
64 位 Python、Tesseract、Ghostscript 三个安装器按顺序装完（Python、Tesseract 可走 winget，Ghostscript 手动装），OCRmyPDF 本体用本地 wheel 安装，全程不连 PyPI：
pip download ocrmypdf -d ./wheels pip install --no-index --find-links=./wheels ocrmypdf⚠️ 两条命令分别在在线机和离线机执行。第二条里的--no-index是关键：它让 pip 完全不连网络索引，只从本地./wheels目录里找包——离线安装能不能"零联网"，就看这一参数。另外官方不支持 32 位 Windows。
macOS：整包迁移 Homebrew 前缀
有网机上执行brew install ocrmypdf（含 Tesseract、Ghostscript、英语包），然后把整个 Homebrew 前缀目录连同下载缓存归档打包拷贝；离线机装好 Homebrew 后解开即用。若还要识别其他语言，先在有网机执行brew install tesseract-lang备下全量语言包再迁移，避免离线机上临时补包。
4. 部署后的两条自检命令，外加五个最常见的坑
部署完别急着处理文件，先跑两条命令确认环境完整：
ocrmypdf --version tesseract --list-langs第一条能打印版本且无报错，说明外部依赖（Python、Tesseract 等）都已就位；第二条列出本机可用的语言包，离线识别中文前确认chi_sim在其中。
出了问题大概率是下面这五种之一，对着症状找对策：
| 症状 | 对策 |
|---|---|
Tesseract couldn't find a language data file | 语言包没放到位，把.traineddata拷入tessdata目录；目录不在默认位置时用TESSDATA_PREFIX环境变量指过去 |
| Tesseract 报打不开 config file 'hocr' | 手工拼的tessdata缺configs/子目录，从完整安装中补齐 |
| 提示某些文字没有可用字形 | 安装对应文字体系的 Noto 字体包；文本层仍可搜索，仅高亮显示受影响 |
| 大文件处理时内存不足 | 用--pages指定页码分段处理，或加大交换空间 |
--clean报 unpaper 缺失 | 安装 unpaper；装不了就省掉--clean，其余功能不受影响 |
5. 处理第一份扫描件：从一张打字机稿到可搜索 PDF，再到批量化
用仓库自带的黑白打字机扫描件tests/resources/typewriter.png（4000×2864 像素）演示完整流程：
ocrmypdf --language eng --clean --output-type pdfa tests/resources/typewriter.png recipe.pdf参数逐条说明：
--language eng：识别英语，即该扫描件的语言；中文文档换成chi_sim--clean：识别前先做去噪清洗，扫描质量越差收益越大（依赖 unpaper）--output-type pdfa：输出 PDF/A 存档格式，适合长期保存- 最后两个位置参数：输入文件、输出文件
跑完用 PDF 阅读器打开recipe.pdf：页面看起来还是那张扫描图，但文字已经可以框选、复制、搜索——文本层就压在图像底下。如果输入是图文混排文档，加--mode skip即可跳过已有文本的页，只处理纯扫描页。
文件多起来就批量化：最朴素的方式是一个循环，对当前目录每个 PDF 生成带ocr_前缀的副本：
for f in *.pdf; do ocrmypdf --language eng "$f" "ocr_$f"; done仓库的misc/batch.py是现成的批量示例，递归查找目录中的 PDF 并逐个处理，复制一份按需改目录参数即可。想再进一步，misc/watcher.py可以盯着一个目录，新放进来的 PDF 自动走一遍 OCR——它依赖额外组件，在线装一次pip install ocrmypdf[watcher]，离线机上照常运行。
各系统的完整安装细节与语言包获取方式，详见官方文档：
- 安装文档
- 语言支持文档
【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
