开启 incremental 是提升二次构建速度最直接有效的方式，需同时配置 "incremental": true 和 "composite": true，并指定 tsBuildInfoFile 路径；单独启用 incremental 可能失效，composite 保障增量逻辑可靠运行。
在 TypeScript 中，开启 incremental 是提升二次构建速度最直接有效的方式。它让编译器只重新处理修改过的文件及其依赖，跳过未变动部分，大幅缩短构建耗时——实测可将平均构建时间从 18.7 秒降至 4.2 秒。
tsconfig.json 中启用增量编译的关键配置
只需在 compilerOptions 中添加以下两项：
- "incremental": true —— 启用增量编译机制
- "composite": true —— 必需配合使用（尤其在项目引用或 monorepo 场景下），确保构建信息可复用且类型检查稳定
完整示例片段：
{
"compilerOptions": {
"incremental": true,
"composite": true,
"tsBuildInfoFile": "./dist/.tsbuildinfo",
"target": "ES2020",
"module": "ESNext",
"strict": true
},
"include": ["src/**/*.ts"]
}
注意：tsBuildInfoFile 路径建议显式指定（默认为 .tsbuildinfo），避免与源码目录混杂；该文件由 TypeScript 自动生成和维护，不应手动修改或提交到 Git。
为什么必须配 composite？
单独开 incremental 在某些场景（如多项目引用、声明合并）下可能失效或触发全量重建。composite: true 会强制生成 tsconfig.tsbuildinfo 并启用更严格的项目边界管理，保障增量逻辑可靠运行。VSCode 构建任务、tsc --watch、CI 环境都依赖这一组合。
配合开发工具真正落地
光配 tsconfig 不够，还需对接实际构建流程：
- 命令行中运行
tsc -p tsconfig.json --watch，自动监听并增量编译 - VSCode 中配置
.vscode/tasks.json，调用tsc --watch并启用$tsc问题匹配器，保存即编译+错误定位 - Webpack + ts-loader 场景下，建议同时开启
transpileOnly: false（保留类型检查）并确保fork-ts-checker-webpack-plugin与增量编译兼容
常见误区与避坑点
以下操作会导致增量失效，回归全量编译：
- 每次调用
createIncrementalProgram时传入不同的rootNames（应固定为整个项目的入口文件列表） - 删除或重命名
.tsbuildinfo文件后未清理缓存，或误删node_modules/.cache中相关中间产物 - 在 CI/CD 中未保留上一次构建的
.tsbuildinfo和输出目录结构，导致无法比对差异 - 混用
skipLibCheck: false且 node_modules 频繁变动，拖慢增量判定
