企业官网建设流程全解析

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 依然能搜到，问题几乎不在 OCR 引擎，而在字体。OCRmyPDF 是给扫描 PDF 添加可搜索文字层的工具，它渲染文字时采用"逐词自动选字体 + 四级回退"机制。看懂这套机制，你既能解释文字层为什么是空白，也能在日志出现告警时准确知道该装哪个字体。

一、文字层为什么可搜索却不可见：字形覆盖与兜底字体

现象：跑完 ocrmypdf，搜索、复制都正常，一高亮却是空的。

原因：PDF 文字层本质是"字符流 + 坐标 + 字体"三件套。某个字符在字体文件里没有字形（glyph），阅读器画不出来，就只能留白。OCRmyPDF 的兜底方案是无字形字体 Occulta.ttf：任何系统字体都盖不住的字符，都用它写进文档。文字层因此仍可搜索、可复制，只是高亮时不可见。

打个比方：Occulta 像一枚"空白印章"——印能盖下去（可检索），但不留墨迹（不可见）。

结论：隐形文字层不是故障，是安全网。想让它显形，唯一办法是装一个覆盖该文字系统的字体。

二、一个词到底用哪个字体：四级选择机制

选字逻辑集中在 多字体管理器 的select_font_for_word()，逐词执行四级查找：

1. 语言优先：hOCR 行的语言标记（如chi_sim）直接指向对应字体，例如 NotoSansSC。
2. 固定候选表：按顺序试拉丁、阿拉伯、天城文、CJK 等约 30 个 Noto 字族，命中即停。
3. 全盘扫描：再不行，就翻遍系统里安装的所有 Noto 字体（macOS 上约有上百个），按字形覆盖率匹配。
4. 最终兜底：全部落空才交给 Occulta，并按语言打一次告警日志。

选中的结果会按"词 + 语言"缓存，同一个词不会反复查找。写进 PDF 的动作则由基于 fpdf2 的 PDF 渲染器 完成。

类比一下，这套流程像派遣翻译：先找该语言的常驻译员，再翻候补名册，最后才全城搜寻。

结论：绝大多数"字体不对"的情况在第 2 级就解决了，走到第 4 级才需要你看日志动手。

三、字体从哪来：内置只有 2 个，其余靠系统扫描

字体提供器 把来源拆成三层：

• 内置提供器：安装包只捆了两个文件——NotoSans-Regular.ttf（拉丁、希腊、西里尔）和Occulta.ttf。这是刻意设计，不塞全部 CJK 字体是为了控制体积。
• 系统提供器：见 系统字体扫描，按需懒加载，扫 Linux 的/usr/share/fonts、~/.fonts和 macOS 的/Library/Fonts等标准目录，支持.ttf/.otf/.ttc以及可变字体（NotoSansSC[wght].ttf这种带括号轴名的文件）。
• 链式提供器：先问内置、再问系统，谁先命中用谁。

结论：干净的 Linux 服务器不装中文字体时，中文文字层默认隐形。这是环境缺件，不是代码问题，装字体就是解法。

四、动手集成：3 步装好中文字体并验证

第 1 步，安装字体（Debian/Ubuntu 为例）：

sudo apt install fonts-noto-cjk

一条命令装好 Noto Sans CJK 全家族，覆盖简繁中文、日文、韩文。如果想看源码实现，可执行git clone https://gitcode.com/GitHub_Trending/oc/OCRmyPDF。

第 2 步，确认字体能被扫描到：

fc-list :lang=zh | head -3

输出里出现 NotoSansCJK 或 NotoSansSC，说明系统扫描这一层已经就绪。

第 3 步，重新跑 OCR 并盯日志：

ocrmypdf --language chi_sim scan.pdf out.pdf

--language同时告诉 Tesseract 识别语言，并给字体选择提供优先提示。日志里没有 "No installed font has glyphs" 告警，中文层就会正常显示。

想程序化确认，也可以跑：

from ocrmypdf.font import MultiFontManager m = MultiFontManager() print(m.has_font('NotoSansSC-Regular'))

返回True即字体链已经接住中文字体。

五、常见坑自检清单：5 项逐条过

• ⚠️ 日志有 "No installed font has glyphs for..."？告警会直接点名缺失字符的 Unicode 码点和该装的 Noto 字族，照着装即可。
• 高亮空白但搜索正常？该词已落到 Occulta 兜底，回上一条处理。
• 字体都装了，个别混排词仍不可见？OCRmyPDF 一个词只用一种字体，单个词跨两种文字系统且无单一字体覆盖时，这是预期行为，多装字体也无效。
• fc-list能看到字体，OCRmyPDF 却找不到？系统扫描只认 Noto* 命名，非 Noto 字体不会入选，换成对应 Noto 字体即可。
• 文件名带方括号，如NotoSansSC[wght].ttf？那是可变字体，已被支持，无需任何额外配置。

过完这 5 项，你的文字层应当做到既能搜、又能看。下一步若想做更深的字体定制，从 插件文档 的插件接口入手；字体与渲染的细节可继续读 进阶文档。

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