使用 vue-tsc --build 和 composite 优化 TypeScript 项目构建

---

一、增量编译与构建效率

1. 增量编译（Incremental）

   • 在 TypeScript 中，如果设置了 incremental: true，编译器会生成一个 .tsbuildinfo 文件来缓存构建信息。下次构建时，只需重新编译更改部分，从而提升速度。
   • vue-tsc --build 与 tsc --build 相同，都能读取上述缓存文件并实现增量编译。如果未指定 tsBuildInfoFile，则默认在当前目录生成 .tsbuildinfo 文件，也可自行配置目录。

2. --force 参数的影响

   • vue-tsc --build --force 会忽略已有缓存，直接进行全量构建，适用于缓存损坏或需要一次性完整验证的场景。
   • 日常开发中无需频繁使用 --force，否则会丢失增量编译带来的效率提升。

3. 常用优化手段

   • 在 tsconfig.json 中启用 incremental 或 composite，并指定 tsBuildInfoFile 存放缓存信息。
   • 根据项目结构，合理设置 include、exclude，减少对无关文件的检查。
   • 仅在配置重大变更或缓存异常时使用 --force，保持增量编译的优点。
   • 定期更新 TypeScript、vue-tsc 等依赖，获取最新性能优化与错误修复。

---

二、composite 与项目引用（Project References）

1. composite 的作用

   • 当 composite: true 时，TypeScript 会自动启用增量编译，同时要求显式配置 rootDir 和 outDir。这样在生成的 .tsbuildinfo 文件中可以记录构建状态，实现高效的增量构建。
   • composite 也是开启 项目引用（Project References） 的关键，允许在顶层 tsconfig.json 中通过 references 字段来声明对其他子项目的依赖。

2. 启用项目引用

   • 在多模块或大型项目里，往往需要将代码拆分为多个子项目，每个子项目都可以独立构建与测试。
   • 通过在顶层 tsconfig.json 里使用：
     json

     Copy Code

     1{
     2  "files": [],
     3  "references": [
     4    { "path": "./packages/core" },
     5    { "path": "./packages/utils" }
     6  ]
     7}

     实现对各子项目的依赖声明。构建时只需在顶层运行 tsc --build 或 vue-tsc --build，便会按照依赖顺序编译各子项目，并缓存构建信息。

3. 项目引用的好处

   • 增量构建：只编译和检查变更过的子项目，减少重复编译。
   • 模块化管理：每个子项目都拥有自己的 tsconfig.json、src、dist 等目录结构，独立维护更清晰。
   • 严格的依赖顺序：TypeScript 会先构建被依赖的子项目，再构建依赖它的项目，避免手动管理构建顺序的麻烦。

4. 注意事项

   • 必须显式设置 rootDir 和 outDir，否则 TypeScript 无法确定输入、输出文件路径。
   • 至少包含一个显式的 files、include 或 exclude，以免无法识别编译范围。
   • 如果 .tsbuildinfo 文件损坏或需要完整构建，可删除该文件或使用 --force 进行一次全量编译。

---

三、在 Vue 项目中的使用

1. vue-tsc 工具

   • vue-tsc 是 TypeScript 用于 Vue 单文件组件（.vue）类型检查的命令行工具，底层基于 TypeScript 编译器工作。
   • 当运行 vue-tsc --build 时，它会读取 tsconfig.json 或 vue-tsconfig.json（如果有的话），并在其中找到与增量编译、项目引用相关的配置。

2. .vue 文件的处理

   • 在增量编译模式下，如果只修改了部分 Vue 单文件组件，vue-tsc --build 只会重新处理发生变化的文件，而不会重复检查未变动的部分。

3. 与常规 TypeScript 项目的差异

   • 除了需要支持 Vue 单文件组件外，其他增量编译和项目引用配置几乎与纯 TypeScript 项目一致。

---

四、综合建议

1. 配置增量与项目引用

   • 对于大型或多模块项目，建议在各子项目 tsconfig.json 中启用 composite: true，并在顶层配置文件使用 references 指明依赖关系，配合 vue-tsc --build 享受增量构建带来的效率。

2. 保留缓存文件

   • 平时不要随意删除 .tsbuildinfo 文件，并谨慎使用 --force 参数，确保增量编译正常工作。

3. 提升构建速度与质量

   • 通过合理的文件组织、清晰的依赖管理和 include/exclude 配置，不仅能在大型项目中显著缩短构建时间，还能增强可维护性和可读性。

4. 排查与调试

   • 若发现类型检查结果异常或构建结果与预期不符，可尝试删除 .tsbuildinfo 文件进行全量重建，或使用 --force 重新构建进行调试。

---

利用 composite: true 与 vue-tsc --build 的增量编译机制，可以在日常开发和部署中大幅提升构建效率，并保持项目的模块化与依赖有序。对于大型或多模块的 Vue 项目，这种方式能够有效减少重复工作，增强代码质量与构建速度。