TypeScript tsBuildInfoFile 怎么把增量构建缓存放到统一目录

在 compilerOptions 中开启 incremental，并把 tsBuildInfoFile 显式设为文件路径，例如 ./.cache/ts/app.tsbuildinfo。这样缓存集中在 .cache/ts，JavaScript 产物仍由 outDir 决定。统一目录不等于共用文件：不同构建配置应各自使用独立文件名。

官方地址：https://www.typescriptlang.org/tsconfig/tsBuildInfoFile.html

先把小项目的路径约定写清楚

假设已有使用本地 TypeScript 依赖的项目，在项目根目录放置 tsconfig.json。下面是最小配置，使用普通增量编译，不需要为了移动缓存而额外引入项目引用。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "incremental": true,
    "rootDir": "./src",
    "outDir": "./dist",
    "tsBuildInfoFile": "./.cache/ts/app.tsbuildinfo"
  },
  "include": [
    "src/**/*.ts"
  ]
}

其中 incremental 负责保存供后续编译复用的项目信息，tsBuildInfoFile 负责指定状态文件。rootDir 取 src，outDir 取 dist。缓存名 app.tsbuildinfo 是本项目选定的名称，不是编译器要求的固定名称；不要只填一个目录然后期待它自动补齐文件名。

配置中保持 JSON 语法，不插入注释；字段含义在正文解释。本文配置、代码和路径是说明性示例，没有实际运行，不提供编译耗时或缓存命中的实测结论。

补一个源文件，区分源码、产物和缓存

创建 src/index.ts，内容如下。这个项目只演示路径规划，不涉及框架、打包器或第三方运行库。

// src/index.ts：仅用一个函数说明源文件与产物的路径关系
export function formatLabel(name: string): string {
  return `记录：${name.trim()}`;
}

按配置推导，源文件位于 src/index.ts，JavaScript 输出对应 dist/index.js，增量信息对应 .cache/ts/app.tsbuildinfo。目录关系如下；这是计划结构，不是终端执行结果。

project/
  tsconfig.json
  src/
    index.ts
  dist/
    index.js
  .cache/
    ts/
      app.tsbuildinfo

这份缓存不属于应用运行时依赖，部署 JavaScript 时不需要把它当作业务资源。它保存编译相关信息，而不是替代 dist 产物。把文件放到统一位置的直接收益是便于管理目录，并不能单凭路径改变承诺编译一定更快。

为什么设置 outDir 后，缓存还会出现在根目录？

因为未显式指定 tsBuildInfoFile 时，默认路径还受 rootDir、outDir 等选项共同影响。官方给出的规则包含一种情况：同时设置 rootDir 和 outDir，按从 rootDir 到配置文件的相对路径拼接缓存位置。

例如配置在项目根，rootDir 为 src，outDir 为 dist。从 src 指向根目录配置文件需要向上一层，默认路径拼接后可能回到项目根。看到缓存没有留在 dist，不必立即认定 outDir 无效。本文直接指定 tsBuildInfoFile，就是避免依赖这组默认推导。

不要用修改 rootDir 的方式单纯搬缓存，因为它还影响输出层级。rootDir 也不是文件筛选器：需要调整输入范围时应检查 include、files 等设置，而不是期待 rootDir 自动排除其他输入。

两个配置能放在同一目录吗？

可以，但不要指向同一个缓存文件。以根目录的 tsconfig.app.json 和 tsconfig.tools.json 为例，可分别选用 ./.cache/ts/app.tsbuildinfo 与 ./.cache/ts/tools.tsbuildinfo。它们的源码和产物配置也应符合各自用途，不是只改缓存名就能隔离整个构建。

若公共配置通过 extends 被多个子配置继承，建议把通用语言选项放在基配置，把具体缓存文件路径留给各子配置。相对路径依据声明它的配置文件解析，不会因为继承而自动改为子配置目录。

例如子配置位于 packages/ui/tsconfig.json，想写入仓库根的 .cache/ts，可在该子配置里指定 ../../.cache/ts/ui.tsbuildinfo。这个相对路径只适用于上述层级；迁移配置文件位置后，应重新按其声明位置计算，不能机械复制。

本地怎样使用，集成时保留什么？

在已安装本地 TypeScript 的项目中，可以按下面命令使用配置。示例通过 --project 明确选定文件，不把源码文件名追加到命令尾部来代替项目配置。

# 从小项目根目录编译，读取同目录的显式配置
npx tsc --project ./tsconfig.json

# 后续编译仍使用同一配置；这是使用示例，不代表实测缓存命中
npx tsc --project ./tsconfig.json

把缓存目录加入版本控制忽略规则，是本项目的管理约定。以下内容可放入项目根的 .gitignore；如果仓库已有同名目录约定，应先结合现有规则安排。

# 本项目的生成目录不作为源代码提交
/dist/
/.cache/ts/

缓存可以删除，后续编译会重新生成相应状态。但清理缓存不等于清理旧 JavaScript，移动缓存配置也不会自动删除旧位置留下的文件。尤其不要把“dist 已清空、缓存仍保留”当作可直接交付的产物状态；项目构建流程应让输出文件和缓存状态配套处理。

接入 CI 时应先明确缓存所属的项目、配置和工具链，再决定保存哪些目录。若任务的目的只是整理工作区，先完成显式路径和独立文件名就够了，不必把缓存分发系统也混进此次修改。

几个常见问题

只写 tsBuildInfoFile 就等于开启增量编译吗？不能这样理解。本例同时显式设置 incremental: true；文件路径选项与启用增量模式承担不同职责。

改变缓存目录会改变 JavaScript 的导入路径吗？缓存路径本身不负责 JavaScript 输出位置。若 dist 的目录层级变了，应另查 rootDir、outDir 及输入文件安排。

文件存在就说明这次构建成功吗？不能。它不是发布成功凭证，构建脚本仍须依据编译命令状态和所需产物处理后续工作，不用缓存文件存在代替结果判断。

需要编辑 tsbuildinfo 的内部字段吗？这个任务只需配置它的位置，不需要修改内容。把它视为编译器维护的生成状态，保留源码与配置作为项目的可维护输入。

参考：tsBuildInfoFile、incremental、rootDir、outDir、extends 官方配置说明。