- OCR
- CLI
【免费下载链接】OCRmyPDF
OCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched
v17 是 OCRmyPDF 的一个里程碑式主版本。它以--pdfa-backend与--output-type auto为支点，重构了 PDF/A 生成链路：OCRmyPDF 自己的 pikepdf 转换 + 校验，配合 Ghostscript 兜底，让 Ghostscript 从必需依赖降级为可选依赖；同时引入 pypdfium2 栅格化、--ocr-engine可插拔 OCR 引擎、OcrOptions参数模型与 fpdf2 文本渲染器，并借助--max-ocr-image-mpixels、零拷贝图像优化等手段显著降低峰值内存、加速大图处理。读完本文，你将掌握 v17 的 PDF/A 后端选择、处理模式（--mode）语义、参数迁移路径、内存预算公式与插件迁移要点，并能直接复用于真实扫描文档归档工作流。
一、v17 主线：让 PDF/A 生成“先去 Ghostscript 化”
1.1 背景：v17.0.0 之前，PDF/A 依赖 Ghostscript
在 v16 及更早版本中，Ghostscript 是 OCRmyPDF 的必需依赖：PDF/A 转换必须经过 Ghostscript，这也意味着图像必然被重新编码、颜色可能被转换，而且每个平台上的输出并不完全一致。
v17.0.0 打破了这一格局。正如 docs/releasenotes/version17.md 的 “Dependency changes” 小节所列：
- 栅格化（PDF → 图像）：
pypdfium2或ghostscript二选一（推荐两者都装）； - PDF/A 生成：
verapdf或ghostscript二选一（推荐两者都装）； - Ghostscript 从 Required 降为 Recommended；
- 新增 fpdf2 作为文本层渲染的必需依赖。
这一变化的关键实现位于 src/ocrmypdf/_pipeline.py：OCRmyPDF 先用 pikepdf 自己“投机式”地完成 PDF/A 声明修补（speculative conversion），再用验证器检查结果，只有验证不通过时才回退到 Ghostscript。
1.2 v17.8.0：恢复“默认输出 PDF/A”并引入双验证器回退
v17.8.0 让--output-type auto（默认值）再次默认产出 PDF/A，行为与 v16 的 “PDF/A by default” 对齐（docs/releasenotes/version17.md 的 v17.8.0 一节）：
- 先尝试快速的无 Ghostscript 路径（当时由 veraPDF 校验）；
- 若无法产出 PDF/A，回退到 Ghostscript；
- 只有当 Ghostscript 也无法安全转换时（例如输入含有未嵌入的 CID/CJK 字体），才输出普通 PDF。
由此带来的行为影响是：默认路径可能再次调用 Ghostscript（更慢，且可能转码图像）。文档明确指出，想完全跳过 PDF/A 转换，请用--output-type pdf。同时，v17.8.0 修复了 veraPDF 1.30.0+ 的检测问题——新版 veraPDF 在版本号之前先打印 JVM 警告，导致 OCRmyPDF 误报“veraPDF 不可用”而跳过快速路径。
另一个值得注意的修复：非嵌入 CID（CJK）文本层不再被静默破坏。PDF/A 要求所有字体嵌入，Ghostscript 会替换并重新嵌入非嵌入的 CID 字体（例如 Acrobat 给扫描版 CJK 文档加的 OCR 文本层），从而损坏文本、破坏可搜索性。v17.8.0 在转换前检测非嵌入 CID 字体：
--output-type auto（默认）：产出普通 PDF 并保留原有文本层；- 显式
--output-type pdfa*：直接报错，绝不产出损坏文件。
1.3 v17.13.0：--pdfa-backend三选一 + 弃用 veraPDF
v17.13.0 把 PDF/A 生成路径固化为一个显式选项--pdfa-backend {auto,ghostscript,internal}（API 参数pdfa_backend=），并完全弃用 veraPDF：
- 无 Ghostscript 的 “投机式”转换现在改用 pikepdf 的 PDF/A 校验（
pikepdf.pdfa），并在元数据与优化步骤之后再次校验最终输出； - veraPDF 不再是必需项，因此即使 Docker 镜像里没装 veraPDF，也能走无 Ghostscript 路径；验证不通过的文件仍回退到 Ghostscript，可用
-v 1查看具体原因。
命令行定义见 src/ocrmypdf/cli.py，三种后端的语义如下：
--pdfa-backend | 行为 | 适用场景 |
|---|---|---|
auto（默认） | 先尝试 OCRmyPDF 自身的转换与校验，不通过再回退 Ghostscript | 绝大多数用户，兼顾速度与兼容性 |
internal | 绝不用 Ghostscript；JPEG 原样直通。结果未通过校验时：pdfa输出类型以退出码 10 失败，--output-type auto输出普通 PDF | 强调“不改动图像/不引入 Ghostscript”的流水线 |
ghostscript | 始终用 Ghostscript 转换 | 需要 Ghostscript 专有能力或传统一致性输出的场景 |
PDF/A 校验与后端协调逻辑在 src/ocrmypdf/_validation_coordinator.py 的_resolve_pdfa_backend()中实现：internal时若用户同时给出了 Ghostscript 专属选项则报错；auto时若给出了 Ghostscript 专属选项则自动切换为ghostscript并提示。
只有 Ghostscript 才实现的选项
以下选项在auto下会强制选择 Ghostscript，在internal下直接报错（对应测试见 tests/test_pdfa.py）：
--pdfa-image-compression：PDF/A 图像压缩策略（v17.6.0 起auto在-O0下选无损，避免 Ghostscript 把无损图转成 JPEG；lossless让既有 JPEG 原样直通）；--ghostscript-jpeg-quality与--ghostscript-jpeg-maxdpi：调整 Ghostscript 的 PDF/A JPEG 输出质量/最大 DPI（v17.5.0 新增，优化器侧的--jpeg-quality仍是推荐的文件体积控制项）；--color-conversion-strategy取值CMYK、Gray或UseDeviceIndependentColor。
投机式转换现在支持的修复
v17.13.0 的投机式转换扩展支持 PDF/A-1b，并自动修复那些过去“必然送去 Ghostscript”的常见问题：
- 将其他输出意图替换为 sRGB；
- 移除图像插值（interpolation）标志；
- 为注释设置 Print 标志；
- 补上 PDF/A-1 要求的
/CIDSet； - 移除 PDF/A 不允许的 XMP 属性和隐藏注释（隐藏注释会在 Ghostscript 运行前移除，并给出与投机式转换一致的警告，而非静默删除）。
同时，v17.13.0 将依赖下限提升为pikepdf[pdfa]10.15+，pdfaextra 会带入jsonschema、referencing、fonttools（Debian 与 Red Hat 均已打包）。
二、v17.0.0 架构重构：模式、引擎、渲染器与参数模型
2.1--mode：六种处理模式统一旧标志
v17.0.0 用--mode（-m）整合了旧版散落的处理标志。枚举定义在 src/ocrmypdf/_options.py，CLI 帮助文本见 src/ocrmypdf/cli.py：
--mode | 语义 | 对应旧标志 |
|---|---|---|
default | 页面上发现已有文本则报错（标准行为） | 默认行为 |
force | 栅格化所有内容并 OCR，保留超链接 | --force-ocr |
force-ocr-no-links | 同force，但丢弃超链接 | v17.13.0 新增 |
skip | 跳过已有文本的页面 | --skip-text |
redo | 剥离旧文本层并重新 OCR | --redo-ocr |
strip | 原地移除不可见 OCR 文本层，不做 OCR | v17.6.0 新增 |
旧标志-f/--force-ocr、-s/--skip-text等仍作为静默别名保留（src/ocrmypdf/_options.py 中会在构造 OcrOptions 时把旧标志映射到对应 mode）。v17.13.0 起，--force-ocr与--deskew、--clean-final一样会把链接注释迁移到栅格化后的页面上，而--mode force-ocr-no-links保留旧行为（测试见 tests/test_links.py）。
--mode strip只移除以不可见文字（PDF 文本渲染模式 3）绘制的文本层。由于 OCRmyPDF 把文本层作为 Form XObject 嫁接（graft）到页面，v17.11.0 修复了strip/redo找不到自产文本层的问题——现在剥离逻辑会下钻 Form XObject、解析从祖先/Pages节点继承的/Resources，并在文本层被清空后移除残留的“空壳” XObject（src/ocrmypdf/_graft.py）。
2.2--ocr-engine：可插拔 OCR 引擎
v17.0.0 引入--ocr-engine {auto,tesseract,none}（src/ocrmypdf/cli.py）：
auto（默认）：自动选择可用引擎；tesseract：显式 Tesseract；none：完全跳过 OCR，适合仅做 PDF/A 转换或图像处理（如--clean）。
同时，OcrEngine抽象基类（src/ocrmypdf/pluginspec.py）扩展出generate_ocr()方法（src/ocrmypdf/pluginspec.py），允许引擎直接产出 OCR 树，无需先转成 hOCR 再翻译，为第三方 OCR 引擎插件铺路。
--ocr-engine none的实践要点（docs/cookbook.md）：
# 仅做 PDF/A 转换，不 OCR ocrmypdf --ocr-engine none --output-type pdfa input.pdf output.pdf注意：none无法检测页面方向与倾斜，所以--rotate-pages、--deskew与它组合时无效（v17.12.0 起会显式告警）。只旋转/纠偏而不加文本层，请用：
ocrmypdf --tesseract-timeout 0 --rotate-pages --deskew input.pdf output.pdfv17.13.0 修复了--rotate-pages --tesseract-timeout 0只检测方向、不真正旋转的问题。
2.3--rasterizer：pypdfium2 优先
v17.0.0 新增可选的 pypdfium2 栅格化插件：--rasterizer auto（默认）优先 pypdfium2，缺失时回退 Ghostscript（src/ocrmypdf/cli.py）。v17.6.0 起，Ghostscript 栅格化路径为灰度/彩色设备启用-dTextAlphaBits=4 -dGraphicsAlphaBits=4抗锯齿（1-bit 单色设备不受影响），并默认改用pngmonod（误差扩散抖动）替代pngmono，改善浅淡/抗锯齿扫描件的 OCR 输入；1-bit 图像蒙版（stencil）会用灰色/彩色填充色绘制时，栅格器会按填充色把页面提升为灰度或全彩再送 OCR，避免中间调文字被抖动成无法识别的斑点。
2.4OcrOptions：Pydantic 参数模型与插件迁移
v17.0.0 把散落在 argparse Namespace 上的选项集中到Pydantic 模型OcrOptions（src/ocrmypdf/_options.py），验证逻辑收敛到模型层，代码中不再有就地修改选项的行为。插件开发者迁移要点（v17.0.0 “Migration guide”）：
from ocrmypdf._options import OcrOptions def check_options(options: OcrOptions) -> None: # 原: options: Namespace ...- 属性访问不变：
options.languages、options.output_type等； - 删除任何就地修改选项的代码，改为在使用点计算；
- 多数插件因鸭子类型兼容仍可无改动运行；
- v17.11.0 起，插件集在每个解释器内只安装一次并被复用（不再每次
ocrmypdf.ocr()都重新执行插件模块），插件不得依赖“每任务重执行”，也不得在插件管理器上存放每任务状态——并发任务会共享同一插件集。
同时，v17.0.0 为 OCR 引擎插件开发者新增导出：OcrElement、OcrClass、BoundingBox（src/ocrmypdf/models/ocr_element.py）。
三、性能与内存：v17 的“数值账本”
3.1--max-ocr-image-mpixels：可预测的内存上限
v17.11.0 新增--max-ocr-image-mpixels（API：max_ocr_image_mpixels=），当页面超过给定百万像素时对送 OCR 的图像降采样。关键特性（src/ocrmypdf/cli.py、src/ocrmypdf/_pipeline.py）：
- 可见页面永不降采样，任何模式（含
--force-ocr）下输出外观都不受影响； - 代价是超高分辨率扫描件的 OCR 精度；
- 默认
None（不设限），传 0 或负数会被 OcrOptions 拒绝（Input should be greater than 0）。
文档给出的量化数据：一张 34 百万像素的页面，峰值内存从 492 MB 降到 325 MB，且识别结果相同。内存估算公式（CLI 帮助原文）：峰值内存 ≈ (--jobs) × 16 字节 × (最大页面的百万像素数)。
docs/performance.md 给出实战建议：
ocrmypdf --max-ocr-image-mpixels 8 --jobs 2 input.pdf output.pdfTesseract 针对约 300 dpi 调优、400 dpi 以上收益甚微，所以 A4/信纸页面用 8 MP 上限通常“免费”；小字号文档请先验证结果再采用。配套测试 tests/test_ocr_image_budget.py 验证了三点：默认不设限、超过上限会降采样且宽高比必须保持（否则文本层对不齐）、上限大于页面尺寸时不做任何重采样。
需要注意两个易混淆选项：
--max-image-mpixels（默认 250.0）是 Pillow 的解压缩炸弹防护，超限中止任务而非降采样，不是内存控制；- 并发进程内任务必须使用相同的
max_image_mpixels——Pillow 的解压缩炸弹限制是解释器全局的，最后一个设置者生效（v17.11.0 “Known limitation”）。
3.2 图像优化提速：直接改包，不再解码重编码
v17.11.0 在图像优化上做了两处“零成本”改造：
- Flate+PNG predictor 图像直接改包成 PNG：
/FlateDecode加 PNG predictor 的流，其内容本就等同于 PNG 的IDAT块，因此直接重打包为 PNG，不再解码成位图再编码。文档数据：6 页文档含一张 9000×9000 图像，优化步骤从 3.4s 降到 0.6s（再叠加下述 JPEG 改动到 0.04s），总运行时间从 10.0s 降到 7.0s，输出逐字节不变（压缩数据原样复用）； - JPEG 只在会用到解码结果的代码路径上解码：
--optimize 1（默认）及以下级别不会重编码 JPEG，过去却一律解码，现在只在实际使用时才解码。
此外，无/Filter的未压缩图像不再产生误导性的“无法优化”警告（此前会内部抛IndexError再被兜底处理器包装成警告）。v17.13.0 还大幅加速了输出文件校验：每个流按其压缩方式用“最廉价方式”检查，不再整体解码，并显示进度条；JPEG 2000 与 CCITT 图像也纳入检查（代价是“未截断但内部损坏”的 JPEG 不再能被检出）。
3.3 单进程内的并发 OCR 任务
v17.11.0 允许在单个 Python 进程中并发运行多个 OCR 任务：
- 此前
ocrmypdf.ocr()全程持锁，第二个线程的调用必须等第一个完成；现在插件状态由读写锁保护——安装插件集取独占锁，任务运行取共享锁； Executor.pool_lock被保留但不再获取（已弃用，将在未来主版本移除），进度条的“单控制台独占”不变量改由进度条自身保证（若已有进度条占据控制台则自我禁用）；- 注意：N 个并发任务各配置
jobs=M现在可能生成最多 N×M 个 worker（过去被串行限制为 M），请相应调低jobs。
3.4 栅格化内存与 use-after-free 修复
- v17.11.0 把大图文件的峰值内存降低约 1/3（34 MP 页面从 752 MB 降到 492 MB）：栅格化不再分配第三个整页缓冲来修正 PDFium 的取整偏差，且堆内存在 OCR 引擎运行前归还给操作系统；
- 同版本修复了 pypdfium2 栅格化的潜在 use-after-free：
to_pil()会让 Pillow 直接别名 PDFium 的位图缓冲（灰度渲染全部如此），而缓冲随即被释放，Pillow 读的是已释放内存。
四、文本层渲染：fpdf2 与“每块 100 条”的 ToUnicode 修复
v17.0.0 用 fpdf2 渲染器取代旧 hOCR 渲染器（--pdf-renderer的hocr/hocrdebug已弃用并重定向到 fpdf2，见 src/ocrmypdf/_options.py），多语言支持与文本定位精度显著提升，配套改进了 Occulta 字形回退字体（零宽标记与双宽 CJK 字符定位）。
v17.12.0 修复了一类影响面极大的 PDF/A 文本提取问题：fpdf2 把每个字体的 ToUnicode CMap 写成单个bfchar块，而 CMap 规范每块最多 100 条；Ghostscript 9.56–10.04.x 遇到超块会丢弃整张映射，导致--output-type pdfa文件中复制/搜索文本变成乱码——任何超过 100 个不同字形的页面（几乎每页正文）都中招。修复方式：OCRmyPDF 在 fpdf2 写出的每个 CMap 块上强制切分到 100 条（对所有 fpdf2 版本生效），实现见 src/ocrmypdf/fpdf_renderer/fpdf2_patches.py 与 src/ocrmypdf/pdfa.py。
同类问题的后续：Ghostscript 10.05.0–10.06.x 会丢弃“一个条目展开成多个字符”的 ToUnicode 条目（fi/ff/fl 连字被抽掉字母，如con dentiality）。v17.12.0 让不需要 shaping 的脚本按“一字一形”编码不可见文本，从根源上消灭这类条目；复杂脚本仍做 shaping，并在检测到受影响的 Ghostscript 时发出警告。v17.4.1 还修复了 RTL 文本提取顺序（阿拉伯 lam-alef 连字等被双向算法打乱）。
五、字体发现与多语言支持
- v17.7.1：字体发现支持可变字体（如
NotoSansArabic[wdth,wght].ttf，Homebrew 与 Google Fonts 的分发形态），此前只匹配静态-Regular.ttf/.otf；CJK 按语言映射到专属 Noto 家族（NotoSansSC/TC/HK/JP/KR），泛 CJK 超字体作为共享回退； - v17.9.0：使用系统上任意已安装的 Noto 字体（不再局限于按名字认识的二十来个字族，macOS 自带上百个 Noto 字面都能用上）；“无字体有字形”的警告现在列出缺失字符的码点与 Unicode 名称，明确指出该装哪个字体家族。字体提供者可实现可选协议
GlyphSearchingFontProvider参与基于覆盖率的字体搜索（src/ocrmypdf/font/ 下的 font_provider 与 multi_font_manager 实现）； - v17.13.0 把 Tesseract 语言码（
deu、fra、ces）正确写入文档/Lang（无两字母码的语言用三字母码）。
六、健壮性加固：恶意/畸形 PDF 与安全
v17 系列在解析层做了大量“宽容失败”加固，处理“结构键位置放着非字典对象”的畸形文件（/Resources、/Root /AcroForm、/Root /Names、注释的/A、图像的/SMask等）时按“键不存在”读取（v17.12.0）；/MarkInfo << /Marked 1 >>以整数代替布尔值的写法不再中止PdfInfo；/UserUnit以 PDF Real 存储时按原文精确读取；LaTeX 产生的内容流畸形数字（如0.000-50131235）现在警告并继续。
--sidecar也加强了校验：拒绝输入/输出文件的任意拼写形式（含./、..、符号链接与文件系统大小写解析后的等价路径），杜绝ocrmypdf in.pdf out.pdf --sidecar ./in.pdf这种静默覆盖输入的隐患。
七、stdout 保护：面向标准输出与插件生态
v17.8.0 起，ocrmypdf input.pdf -在操作系统层面保护标准输出：程序在启动早期（加载插件或启动 worker 之前）保存真实 stdout，把文件描述符 1 重定向到 stderr，确保只有最终的 PDF 字节能到达 stdout。第三方库、插件或任何意外print()都无法再破坏输出流；故意向 stdout 打印的插件，其输出会被重定向到 stderr。对应公共 API 为ocrmypdf.configure_stdout_protection()（src/ocrmypdf/api.py、src/ocrmypdf/main.py），适合需要命令行式行为的调用方；自行管理标准输出的应用不应调用它。
v17.12.1 修复了该机制的副作用：ocrmypdf --version与--help一度被重定向到 stderr，导致version=$(ocrmypdf --version)取空、ocrmypdf --help | less无输出。现在 argparse 自身的输出被路由回真实 stdout，错误信息仍走 stderr。
八、watcher.py：目录监控与安全模型
v17.10.0 对watcher.py（watcherextra）做了现代化与安全加固：
- 用
watchfiles替代watchdog，默认使用原生 OS 文件系统通知，OCR_USE_POLLING=1强制轮询； - 启动时（退出码 9）强制“数据/代码分离”：输入、输出或归档目录若与 Python 解释器路径（
sys.path、虚拟环境、site-packages、$PATH）重叠、OCR_JSON_SETTINGS指向数据目录内或组/全局可写文件、或指定了数据目录内的插件，都拒绝运行；输出/归档目录是输入目录或其子目录时同样拒绝（避免无限循环重处理）； - 运行时不再跟随符号链接、不处理 FIFO/设备等非普通文件，拒绝把输出写到被非普通文件占据的目标；
- 加密 PDF 不再让 watcher 崩溃：
pikepdf.PasswordError不继承pikepdf.PdfError，曾逃过等待文件写完整的处理器、直接撕毁监听循环。现在加密文件被记录并立即跳过（重试也拿不到密码），且任何单文件错误都不能再终止 watcher。
v17.11.0 为 watcher 增加可配置输出布局与冲突策略（仅影响 watcher，不影响ocrmypdf库 API）：
OCR_OUTPUT_STRUCTURE/--output-structure：FLAT（默认，全部直接输出到目标目录）、YEAR_MONTH（{destination}/{year}/{month}/{filename}，替代旧OCR_OUTPUT_DIRECTORY_YEAR_MONTH=1）、HIERARCHY（镜像输入目录树，input/a/b/c.pdf→output/a/b/c.pdf）；OCR_ON_CONFLICT/--on-conflict：目标文件已存在时，SUFFIX（默认，写name (1).pdf、name (2).pdf…）、SKIP（记录并跳过）、OVERWRITE（旧行为）。行为变更：默认从静默覆盖改为SUFFIX；- 输出/归档文件名与目录组件针对更严格的文件系统（如 SMB 共享）做净化：Windows/SMB 非法字符（
<>:"/\|?*与控制字符）替换为_，去掉尾部点/空格，保留 DOS 设备名（CON、PRN、AUX、NUL、COM1-9、LPT1-9）加_前缀； OCR_OUTPUT_DIRECTORY_YEAR_MONTH弃用，由OCR_OUTPUT_STRUCTURE=YEAR_MONTH取代，两者同设时后者生效。
九、其他值得关注的 v17 变更速览
--pages支持end别名（v17.5.0）：--pages 3-end从第 3 页 OCR 到末页；--no-overwrite/-n（v17.4.0）：目标已存在时以退出码 5（OutputFileAccessError）退出；--tagged-pdf-mode（v17.1.0）：允许跳过 TaggedPDF 报错信息；v17.12.0 起被拒绝的 Tagged PDF 以退出码 6（already_done_ocr）退出（原为 2input_file），依赖退出码 2 的脚本需要更新；- HEIC 输入改为可选 extra（v17.12.0）：
pi-heif已停维护，继任者pillow-heif的 wheel 捆绑 libheif/libde265/x265 导致整体为 GPLv2，故默认不安装；需要处理 HEIC 请pip install ocrmypdf[heic]，Docker 镜像与 snap 不含它； - Python API 细节（v17.3.0/v17.4.2）：
language参数曾一直被忽略、默认eng，现已正确映射到OcrOptions.languages并支持eng+deu拆分；tesseract_timeout默认从 0 改为None（回退到插件默认 180 秒）；未显式设置max_image_mpixels时不再无条件覆盖宿主应用的PIL.Image.MAX_IMAGE_PIXELS； - PyInstaller hook（v17.13.0）：OCRmyPDF 自带 hook（src/ocrmypdf/_pyinstaller/hook-ocrmypdf.py），打包引用它的应用无需额外选项（Tesseract 与 Ghostscript 仍需安装）；
- 新增
PageInfo.has_visible_text（v17.13.0）：排除 OCR 层这类不可见文本；has_text不变（src/ocrmypdf/pdfinfo/info.py）； - Docker（v17.7.0）：默认以非 root 用户
app（uid/gid 1000）运行，工作目录默认为/data，Ubuntu 镜像改从发行版仓库安装 Tesseract 5，基础镜像更新至 Ubuntu 26.04 / Alpine 3.24；绑定挂载输入输出目录时可能需要按文档添加--user参数，stdin/stdout 管道模式无需任何权限设置； - 字体替换可复现（v17.13.0）：Ghostscript 替换未嵌入字体时固定使用自带字体（
-dNONATIVEFONTMAP），各平台输出一致（macOS 原生字体查找曾嵌入数十 MB 系统字体），并在替换非标准 14 字体或丢失粗/斜样式时告警； - 时区语义（v17.13.0）：无时区的创建时间按本地时间处理并写入输出日期（可设
TZ改变），并给出警告； - 质量报告（v17.6.0）：优化器遇到无法处理的图像时，输出简洁警告（说明图像保持原样），完整回溯仅在
-v 1时可见。
十、升级到 v17 的迁移清单
针对从 v16 及更早版本升级的团队：
- 确认 PDF/A 后端：默认
--output-type auto现在“尽可能产出 PDF/A”。若你的流水线依赖确定性输出，可显式--pdfa-backend ghostscript；若坚持不引入 Ghostscript，用internal并接受pdfa输出类型的退出码 10； - 脚本退出码：Tagged PDF 拒绝时退出码从 2 变为 6；
--no-overwrite引入退出码 5； - 不要依赖“总是 PDF/A”：无 Ghostscript 且校验不通过时，
auto会输出普通 PDF；含非嵌入 CID/CJK 字体的输入同样如此； - 插件更新：类型标注从
argparse.Namespace改为ocrmypdf._options.OcrOptions，移除就地修改选项的代码，不要依赖“每任务重执行插件模块”； - HEIC 用户：显式安装
ocrmypdf[heic]； - watcher 用户：确认数据目录与解释器路径分离，检查新默认
SUFFIX冲突策略是否符合预期； - 内存预算：利用
--max-ocr-image-mpixels与公式峰值 ≈ jobs × 16B × 最大页面 MP规划内存，注意并发任务会放大 worker 数量。
v17 的完整演进记录见 docs/releasenotes/version17.md，相关实现可继续阅读 src/ocrmypdf/_pipeline.py、src/ocrmypdf/_options.py、src/ocrmypdf/pluginspec.py，实战示例见 docs/cookbook.md 与 docs/performance.md。
- OCR
- CLI
【免费下载链接】OCRmyPDF
OCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched
相关推荐
OCRmyPDF 进阶用法全解：unpaper 控制、OCR 引擎参数、光栅化/渲染器选择与 PDF/A 转换机制
OCRmyPDF 进阶用法全解：unpaper 控制、OCR 引擎参数、光栅化/渲染器选择与 PDF/A 转换机制 本篇基于 OCRmyPDF 官方文档 doc
OCRCLI企业级OCR引擎：Tesseract.js高性能架构与部署指南
企业级OCR引擎：Tesseract.js高性能架构与部署指南 Tesseract.js是一款纯JavaScript实现的OCR引擎，支持超过100种语言的文本
OCR计算机视觉PDF Craft：重新定义PDF文档转换的智能引擎
PDF Craft：重新定义PDF文档转换的智能引擎 你是否曾为扫描版PDF文档无法编辑而头疼？PDF Craft正是为解决这一痛点而生的专业工具，它能将扫描书
AI 应用OCR
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
