Tesseract.js 性能调优指南：从 Worker 复用、语言数据缓存到 corePath 配置，全面降低 OCR 耗时

在 tesseract.js 中，OCR 的总耗时由两部分构成：Worker 的初始化/加载阶段（createWorker）与识别执行阶段（worker.recognize）。本篇基于仓库官方文档 性能指南 系统讲解两套优化策略——"减少设置时间"与"减少识别运行时"，并结合 createWorker 源码、浏览器与 Node 两套缓存实现（浏览器缓存、Node 缓存）以及仓库中的官方示例（basic-efficient.html、scheduler.js），说明每条建议背后的实现原理，让你能针对自己的应用场景做出取舍并验证效果。

性能调优的基本原则

性能指南 的开篇就给出了一条总原则：这些调优技巧中，有些是"避坑型"的（应当普遍实施），有些则涉及改变语言数据或识别模型，可能会损害识别质量。因此：

• 是否采用某项策略取决于具体应用；
• 在把重要设置从默认值改掉之前，应始终对性能与质量同时做基准测试。

仓库为此提供了专门的 benchmarks 目录：其中包含针对预置示例图像（如 tyger.jpg、meditations.jpg）的速度/内存基准示例（浏览器速度基准、Node 速度基准、Node 内存基准）。与"快速运行、二元通过/失败"的单元测试不同，这些基准用于更稳健地评估对 tesseract.js 的潜在变更，正是"改配置前先 benchmark"这一原则的落地工具。

减少设置时间（Setup 阶段优化）

在很多应用中，运行时的大头并不是识别本身，而是 Worker 的创建、代码与语言数据的下载加载。理解 createWorker 的实际行为是优化的前提：

从 createWorker 源码 可以看到，每次调用 createWorker 都会走一条固定的初始化链：

loadInternal()                       // 加载 wasm 核心
  .then(() => loadLanguageInternal(langs))   // 下载语言数据
  .then(() => initializeInternal(langs, oem, config))  // 初始化引擎
  .then(() => workerResResolve(resolveObj));

即"加载核心 → 加载语言数据 → 初始化引擎"三个耗时步骤在每次 createWorker 时都会执行。这也解释了性能文档中的一个提醒：首次用户付出的设置代价在开发期不易被察觉，因为 tesseract.js 首次下载后会缓存语言数据。若想体验"首次用户"的真实开销，可在 createWorker options 中设置 cacheMethod: 'none' 来绕过缓存——文档同时提醒：发布应用前务必移除该设置。

复用 Worker，不要每张图新建

当需要识别多张图片时，"每张图 create / load / destroy 一个 Worker"是永远错误的做法：如果图片是顺序识别的，那么反复创建、加载、销毁 Worker 的额外步骤纯属浪费——同一个 worker.recognize 可以连续处理所有图片，Worker 用一次后不会坏掉。

仓库官方示例 basic-efficient.html 展示了正确姿势：Worker 只创建一次，之后用户上传每个新文件都复用同一个 Worker：

<script type="module">
  // A worker is created once and used every time a user uploads a new file.
  const worker = await Tesseract.createWorker("eng", 1, {
      corePath: '../../node_modules/tesseract.js-core',
      workerPath: "/dist/worker.min.js",
      logger: function(m){console.log(m);}
    });

  const recognize = async function(evt){
    const files = evt.target.files;
    for (let i=0; i<files.length; i++) {
      const ret = await worker.recognize(files[i]);
      console.log(ret.data.text);
    }
  }
  // ...
</script>

反之，如果图片需要并行识别，为每个识别任务新建 Worker 则很可能因资源限制导致崩溃——每个 tesseract.js worker 都会占用较高内存，代码绝不应该能创建任意数量的 Worker。正确的做法是用 scheduler 建立一个固定大小的 Worker 池（例如 4 个），再把任务通过调度器分发。官方示例 scheduler.js 完整演示了这一模式：

const { createWorker, createScheduler } = require('../..');

const scheduler = createScheduler();

// Creates worker and adds to scheduler
const workerGen = async () => {
  const worker = await createWorker('eng', 1, { cachePath: '.' });
  scheduler.addWorker(worker);
};

const workerN = 4;
(async () => {
  const resArr = Array(workerN);
  for (let i = 0; i < workerN; i++) {
    resArr[i] = workerGen();
  }
  await Promise.all(resArr);

  for (let i = 0; i < imageArr.length; i++) {
    resArr2[i] = scheduler.addJob('recognize', image).then((x) => console.log(x.data.text));
  }
  await Promise.all(resArr2);

  await scheduler.terminate(); // It also terminates all workers.
})();

scheduler 通过 addWorker 把 Worker 加入池内、addJob 把任务入队并等待空闲 Worker 领取（目前支持 recognize 与 detect 两种 action），还能用 getQueueLen、getNumWorkers 观察队列与池状态，最后用 terminate 统一回收（API 细节见 docs/api.md 的 createScheduler 章节；浏览器端用法可参考 basic-scheduler.html）。

提前初始化 Worker

不必等到最后一刻才加载代码与数据——提前创建并初始化好 Worker，可以大幅缩短用户第一次执行识别时的等待时间。这正是上面 basic-efficient.html 的做法：Worker 在页面脚本加载时就已创建完成，文件选择框一触发即可立刻开始识别。

至于"什么时候"预加载最合适，文档给出的判断依据是应用特性：例如一个 Web 应用里只有 5% 的用户需要 OCR，那么页面一加载就下载约 15MB 的代码与数据显然不值得；更合理的时机是用户表达出要做 OCR 的意图之后、但还没有选定具体图片之前。

不要禁用语言数据缓存

语言数据是运行 tesseract.js 所需下载中最大的一部分。多数语言数据文件（包括默认的英语文件）约 2MB，但在最坏情况下会大得多：例如把识别模型（oem）设为 Tesseract Legacy 且语言设为简体中文时，需要下载约 20MB 的文件。

为避免重复下载，tesseract.js 会缓存 .traineddata 文件。从源码实现可以看到两套缓存机制：

• 浏览器：browser/cache.js 基于 idb-keyval 封装，读写走 IndexedDB；
• Node.js：node/cache.js 直接封装 fs 的 readFile / writeFile / unlink / access，把语言数据缓存到 cachePath 指定的本地文件。

缓存行为由 createWorker options 中的 cacheMethod 控制，取值为：

cacheMethod	行为
write（默认）	读取缓存并在未命中时写回
readOnly	读取缓存但不写回
refresh	不读缓存，总是重新下载并写回
none	不读也不写缓存，每次全新下载

历史版本中该缓存行为曾存在 bug，导致一些用户把 cacheMethod 设为 'none' 或 'refresh' 来规避问题。这些 bug 已在 v4.0.6 中修复，因此当前建议是：直接使用默认的 cacheMethod 值（即干脆不传这个参数）。只有在你需要模拟"首次用户"开销做性能测试时，才临时设置 cacheMethod: 'none'。

减少识别运行时（Recognition 阶段优化）

使用最新版本的 Tesseract.js

旧版本的 tesseract.js 明显更慢。性能文档给出的参照：已弃用的 v2 版本识别某些图像所需时间是最新版本的约 10 倍。如果你的项目仍锁定在旧版本，升级本身就是收益最大的一项"优化"。

不要把 corePath 指向单个 .js 文件

如果你设置了 corePath 参数，务必把它指向一个包含全部 4 个 wasm 构建文件的目录：

1. tesseract-core.wasm.js
2. tesseract-core-simd.wasm.js
3. tesseract-core-lstm.wasm.js
4. tesseract-core-simd-lstm.wasm.js

tesseract.js 需要能够在这 4 个构建之间自行挑选（SIMD 与否、LSTM-only 与否）。docs/api.md 对 corePath 的描述与 性能指南 一致：网上流传的一些代码片段会把 corePath 直接设为某个具体的 .js 文件，这是强烈不推荐的——为了最佳性能与最低网络开销，tesseract.js 必须保留在各构建间选择的能力，否则会显著降低性能或破坏兼容性。这一点在 createWorker 源码 中也能得到印证：源码会根据 oem 与 legacyCore 选项计算 lstmOnlyCore，随后在 load 阶段把该标志传给 wasm 核心的选择逻辑。

考虑使用"快速版"语言数据

默认情况下，tesseract.js 使用的语言数据是为识别质量而非速度优化的。如果你更看重速度，可以把 langPath 指向快速版数据源进行试验：

const worker = await Tesseract.createWorker('eng', 1, {
  langPath: 'https://tessdata.projectnaptha.com/4.0.0_fast',
});

需要注意文档中的明确声明：官方尚未对快速版数据在性能与准确率上的影响做过基准测试，也就是说"更快"的程度与"掉多少精度"都没有官方数字。如果你做了这样的测试，文档欢迎你向项目提交 Issue 分享结果。结合前述总原则：切换到 4.0.0_fast 属于"可能损害质量"的策略，落地前务必用 benchmarks 的思路对自己的图像集同时测速度与准确率。

优化清单速查

策略	类型	关键操作
复用 Worker	避坑（普遍适用）	多张图共用一个 worker.recognize，不要逐图创建/销毁
并行识别用 scheduler	避坑（普遍适用）	createScheduler + 固定 Worker 池（如 4 个）+ addJob 分发
提前初始化 Worker	场景相关	在用户产生 OCR 意图后、选图之前预建 Worker（见 basic-efficient.html）
保持语言数据缓存开启	避坑（普遍适用）	不传 cacheMethod，使用默认 write；仅性能测试时临时用 'none'
使用最新版 tesseract.js	避坑（普遍适用）	升级到当前版本，旧版（如 v2）慢约一个数量级
corePath 指向完整目录	避坑（普遍适用）	目录须含全部 4 个 tesseract-core*.wasm.js 文件
快速版语言数据	场景相关（可能损质量）	langPath 设为 4.0.0_fast 源，先自行 benchmark 速度与准确率

最后重申官方立场：表中"避坑型"策略建议普遍实施；而涉及模型或语言数据换型的策略（快速版数据、Legacy 模型）可能牺牲质量，是否采用取决于你的应用，改动重要设置前请先对自己真实的图像集做性能与质量的双重基准测试。