如何使用TypeScript编译器API同时实现增量与监听模式？

我正好做过类似的场景，结合TypeScript Compiler API的增量编译能力和Meteor的文件监听，要解决启动扫描慢的问题，核心就是复用同一个编译器宿主（Host）和程序（Program）实例，而不是每次文件变化都从头创建。下面给你一步步拆解实现思路和代码示例：

TypeScript的增量编译依赖两个关键对象的状态留存：

• IncrementalCompilerHost：缓存文件系统的元数据（文件内容、修改时间、tsbuildinfo内容），避免每次都重新扫描整个目录；
• Program：保存已完成的类型检查、符号表、编译结果，增量更新时只处理变化的文件。

1. 初始化可复用的增量编译Host #

首先创建一个全局的IncrementalCompilerHost实例，不要在每次文件变化时重新创建。这个Host会自动缓存文件的读取结果和修改时间，大幅减少文件系统扫描的开销：

import * as ts from "typescript";

// 配置你的编译选项，必须开启增量编译
const compilerOpts: ts.CompilerOptions = {
  incremental: true,
  tsBuildInfoFile: "./.meteor/local/tsconfig.tsbuildinfo", // 存在Meteor的本地缓存目录更合适
  target: ts.ScriptTarget.ESNext,
  module: ts.ModuleKind.CommonJS,
  // 其他你的项目配置
};

// 创建全局复用的增量编译Host
const incrementalHost = ts.createIncrementalCompilerHost(compilerOpts);

// 可选：自定义Host的readFile/writeFile，确保tsbuildinfo被正确持久化
// 比如如果Meteor有特殊的文件访问逻辑，可以在这里适配
const originalReadFile = incrementalHost.readFile;
incrementalHost.readFile = (fileName, encoding) => {
  // 优先从缓存读取，或者适配Meteor的文件系统
  return originalReadFile(fileName, encoding);
};

2. 初始化并持久化Program实例 #

第一次启动时用createIncrementalProgram创建初始程序，之后所有的更新都基于这个实例的增量更新，而不是重新创建：

// 初始Program实例，保存为全局变量
let currentProgram = ts.createIncrementalProgram({
  rootNames: getMeteorSourceFiles(), // 替换成你获取Meteor项目源文件的逻辑
  options: compilerOpts,
  host: incrementalHost,
});

// 第一次编译后保存tsbuildinfo
currentProgram.emit();

这里的getMeteorSourceFiles需要你自己实现，比如从Meteor的项目结构里获取所有需要编译的.ts/.tsx文件，或者直接读取tsconfig的include配置。

3. 响应Meteor的文件变化：增量更新Program #

当Meteor检测到文件变化时，不要重新创建Program，而是调用现有Program的createProgram方法，传入旧实例和变化的文件信息，让TypeScript只处理变化的部分：

// 绑定Meteor的文件监听回调（示例，根据Meteor的API调整）
Meteor.watchPathForChanges("/imports", (filePath) => {
  // 只处理TypeScript文件
  if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx")) return;

  // 告诉Program文件已更新，刷新缓存
  currentProgram.refreshFile(filePath);

  // 增量更新Program：复用旧实例、Host，只重新处理变化的文件
  currentProgram = currentProgram.createProgram({
    rootNames: currentProgram.getRootFileNames(), // 保留现有入口文件，新增文件的话需要追加
    options: compilerOpts,
    host: incrementalHost,
    oldProgram: currentProgram, // 关键：传入旧Program实现增量更新
  });

  // 执行增量编译
  const emitResult = currentProgram.emit();

  // 处理编译错误（可选）
  if (emitResult.emitSkipped) {
    const diagnostics = [...ts.getPreEmitDiagnostics(currentProgram), ...emitResult.diagnostics];
    diagnostics.forEach(d => {
      console.error(`[TS Error] ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`);
    });
  }
});

4. 处理新增/删除文件的特殊情况 #

如果有文件新增或删除，你需要更新rootNames列表，然后再调用createProgram：

function handleFileAdd(filePath: string) {
  const newRootNames = [...currentProgram.getRootFileNames(), filePath];
  currentProgram = currentProgram.createProgram({
    rootNames: newRootNames,
    options: compilerOpts,
    host: incrementalHost,
    oldProgram: currentProgram,
  });
  currentProgram.emit();
}

• 绝对不要每次文件变化都新建Host或Program：这会清空所有缓存，回到全量编译的速度，完全失去增量编译的意义；
• 确保tsBuildInfoFile的路径是可读写的：Meteor的本地缓存目录（比如.meteor/local）是不错的选择，避免提交到版本库；
• 如果修改了编译选项（比如改变target、module），必须重新创建Program：因为选项变化会影响整个编译流程，这种情况建议重启监听；
• 调试时可以开启traceResolution选项：如果遇到增量编译不生效的情况，打开这个选项可以查看TypeScript的文件扫描和缓存逻辑。

内容的提问来源于stack exchange，提问作者Pelle