light-ocr 评测：一个把 PDF、模型和字体都塞进 npm 包的离线 OCR
适用于 Node.js 和 C++ 的快速离线 OCR。 PP-OCRv6 具有 Core ML / WebGPU 硬件加速功能，可通过置信度分数和坐标识别图像中的文本。 npm：@arcships/light-ocr。
秒懂
- 它是什么？
- light-ocr 是面向 Node.js 与 C++ 的离线 OCR 引擎，内置 PP-OCRv6 模型、PDFium 渲染器和中文回退字体，安装即用，无二次下载。本文基于仓库文档与发布记录，评估其机制、限制与适用场景。
- 适合谁用？
- light-ocr 适合需要在 Node.js 或 C++ 应用中做本地 OCR 的团队，尤其是要求安装后无网络、无编译、无额外下载的桌面软件或 CLI 工具。它不适合需要日语识别或追求最小体积的场景，Tiny 模型明确不含日语，Medium 模型体积约 139 MB。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 42 天前。
- 用什么语言写的？
- 主要是 C++（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是安装地狱，而不是识别算法本身
OCR 库的常见痛点不是识别率，而是装配。模型文件、推理运行时、图像解码器、PDF 渲染器、字体，每一项都可能需要单独下载或编译。light-ocr 把这一切打包进一个 npm 包：PP-OCRv6 Small 模型、PDFium 二进制、Noto Sans SC 回退字体，以及 macOS、Linux、Windows 六个平台的预编译组件。文档明确说安装和运行都不需要 postinstall 脚本、编译器和运行时下载。这个设计对桌面应用和 CLI 工具很直接，但对只想在服务器上跑一次识别的用户，30 MB 的模型体积可能显得重。它解决的是分发问题，识别算法本身来自 PaddleOCR 的 PP-OCRv6，light-ocr 的价值在于把模型和运行时封装成一致的接口。
从像素到文本的路径：四种输入，两种执行模式
light-ocr 的输入层很宽：JPEG、PNG、PDF、编码字节或已解码的像素缓冲。像素缓冲支持 GRAY8、RGB8、BGR8、RGBA8 四种格式，这让已经自己解码图像的 Node.js 应用可以跳过重复解码。输出是行级结构，每行包含文本、置信度和四边形坐标，还有页面元数据和耗时。执行模式由 createEngine() 自动选择：macOS 15+ Apple Silicon 优先 Core ML，Linux x64 和 Windows x64 优先 WebGPU，其余平台回退 CPU。这种自动降级策略是务实的，但也是需要警惕的，因为用户可能以为自己在用硬件加速，实际却跑在 CPU 上。文档提供了 execution 选项可以显式指定 auto、cpu、apple 或 webgpu，但没有说明如何确认当前生效的模式，CLI 的 doctor 命令可以输出系统诊断信息，这算是补上了这个缺口。
PDF 支持是内置的，但回退字体有校验门槛
PDF 识别不是简单地把页面转成图片。light-ocr 把 PDFium 二进制和 Noto Sans SC 字体一起打包，目标是为了让引用常见非嵌入中文字体的 PDF 在 OCR 前能正确渲染。文档里提到字体是 checksum-pinned，这意味着加载时会校验 SHA-256。这个设计保证了供应链安全，但也会带来实际问题：如果用户用了一个自签名的重打包版本，签名验证失败，字体加载就会被拒绝。v0.5.7 的发布说明专门提到支持 macOS 重新签名，说明这个校验确实在真实场景中触发过。另外，PDF 默认 DPI 是 150，用户需要自己权衡渲染清晰度和内存占用，文档没有给出不同 DPI 下的性能数据。
安装与运行：三行命令，但平台差异藏在细节里
安装就是 npm install @arcships/light-ocr，然后 import { createEngine }。CLI 也直接可用，light-ocr image.png --format json 输出带坐标的结果。PDF 用 --pages 1-10 指定页范围，jsonl 格式适合流式处理。文档特别强调支持 Node.js 22 和 24，这比大多数库的 LTS 支持范围更窄，如果你还在用 Node 18，装不上。CommonJS 和 ESM 都有导出，TypeScript 类型也包含在内，这对混合模块类型的项目是加分项。但要注意，Tiny 和 Medium 模型是预览版，需要 @next 标签安装，而且 Tiny 明确不支持日语，Medium 的完整语言列表在文档中被截断了，无法确认。如果你需要日语，只能选默认的 Small 模型。
tiled 模式：高分辨率小字体的补救，但不是银弹
文档提到一个可选的 tiled 模式，用于保留高分辨率图像中的小字和密集文字。这个模式显然是把大图切成小块分别识别，再合并结果。它没有出现在默认路径里，说明有额外开销，可能是速度变慢或内存增加。文档没有给出 tiled 模式的具体参数或触发条件，比如块大小、重叠比例、如何合并边界框。对于扫描文档这类典型场景，如果你发现小字被漏掉，可以尝试这个模式，但需要自己测试效果。它不是一个自动开关，而是需要主动启用的选项。如果你处理的是超高分辨率截图或卫星图像，这个模式值得验证，但别指望它能解决所有密集排版问题。
维护成本与许可证：Apache-2.0 的宽松，但升级要留意签名变更
项目采用 Apache-2.0 许可证，这对商业集成是友好的，没有 copyleft 义务。发布节奏看起来活跃，v0.5.5 到 v0.5.7 之间隔了约一周，每次修复都针对具体问题，比如 PDF 渲染回归和 macOS 重签名。升级成本主要在模型和原生二进制的兼容性上，因为 npm 包把模型和运行时捆绑在一起，升级主版本可能意味着模型行为变化，需要重新跑一遍测试集。另一个维护点是签名校验，如果下游打包器重新签名了原生二进制，必须确保签名身份与宿主应用匹配，否则加载会失败。文档对这个机制有明确说明，但实际集成时你需要为打包流程增加签名验证的测试步骤。
替代方案：Tesseract.js 和 PaddleOCR 的取舍
最直接的替代是 Tesseract.js，它在浏览器和 Node 里运行，模型体积小，但速度通常较慢，且没有内置 PDF 渲染器，你需要自己用 pdfjs-dist 把 PDF 转成图片。另一个选择是 PaddleOCR 的官方 Python 包，识别质量可能更高，但需要 Python 环境和模型下载，安装步骤明显更重。light-ocr 的优势在于它把 PDFium 和字体都打包了，而且提供 WebGPU 加速，这在 Node.js 生态里很少见。Tesseract.js 没有硬件加速，PaddleOCR 官方 Node 绑定不成熟。如果你已经有图像解码流程，light-ocr 的 recognize() 接受像素缓冲，可以省去一次编解码。但如果你只需要英文识别且不想引入 30 MB 的模型，Tesseract.js 的英文模型可能更轻。
编辑结论
light-ocr 适合需要在 Node.js 或 C++ 应用中做本地 OCR 的团队，尤其是要求安装后无网络、无编译、无额外下载的桌面软件或 CLI 工具。它不适合需要日语识别或追求最小体积的场景，Tiny 模型明确不含日语，Medium 模型体积约 139 MB。也不适合需要自定义模型或训练流程的用户，因为仓库文档未提及任何训练或微调接口。采用前应验证三件事：确认目标平台在自动模式下是否获得硬件加速，macOS 15+ Apple Silicon 的 Core ML 和 Linux/Windows x64 的 WebGPU 是否按文档生效；检查 PDF 中非嵌入中文字体的渲染是否依赖 Noto Sans SC 回退字体，若字体缺失且未校验 SHA-256 会拒绝加载；以及评估 tiled 模式对高分辨率小字体的实际收益，因为该模式是可选开关，默认未启用。若这些条件满足，light-ocr 的单一 npm 依赖模式确实能省去传统 OCR 栈的装配成本。
社区笔记