TypeScript 编译速度：大型项目编译缓慢

TypeScript 在大型项目中的编译速度往往会随着代码量的增加呈指数级下降。这通常是因为类型检查器需要重新解析所有文件，或者配置不当导致重复工作。解决这一问题需要从配置优化、项目拆分和工具链升级三个层面入手。

一、 诊断编译瓶颈

在动手优化之前，必须先找出时间究竟花在了哪里。TypeScript 提供了内置的诊断工具来输出编译过程的详细耗时。

1. 打开 终端，进入 项目根目录。
2. 运行 以下命令来生成诊断报告：

npx tsc --diagnostics

3. 查看 终端输出的表格。重点关注 Files 数量以及 Milliseconds 总耗时。
4. 观察 Identify、Parse 和 Check 这三个阶段的时间占比。
   • 如果 Parse（解析）耗时过长，通常意味着项目引用了过多不必要的文件。
   • 如果 Check（类型检查）耗时过长，意味着类型系统过于复杂或存在循环依赖。

二、 配置基础优化

通过调整 tsconfig.json 中的关键配置项，可以立即减少编译器的重复工作量。

1. 打开 项目根目录下的 tsconfig.json 文件。
2. 开启 增量编译功能。设置 incremental 为 true，这会让编译器将上次编译的状态信息保存到 .tsbuildinfo 文件中，下次编译时只检查变更的文件。

{
  "compilerOptions": {
    "incremental": true
  }
}

3. 启用 skipLibCheck 选项。设置 skipLibCheck 为 true。

此选项会跳过对声明文件（.d.ts）的类型检查。由于 node_modules 中的类型定义文件通常已经由库作者验证过，且数量巨大，跳过它们可以显著缩短编译时间。

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

4. 缩小 编译范围。检查 include 和 exclude 字段。
   • 确保未将 test、spec 或构建产物目录（如 dist、build）包含在 include 中。
   • 添加 exclude 规则，明确排除非源码目录：

{
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "**/*.spec.ts",
    "**/*.test.ts"
  ]
}

三、 拆分项目引用

对于超大型单体项目，将代码拆分为多个子项目是根本性的提速方案。TypeScript 的“项目引用”功能允许将代码库划分为逻辑单元，编译器可以独立构建和缓存这些单元。

1. 规划 项目结构。将代码库按功能模块拆分，例如将 core（核心逻辑）、ui（界面组件）、utils（工具函数）分开。

假设项目结构如下：

2. 配置 子项目。进入 packages/core 目录，创建 或 修改 tsconfig.json。添加 composite 选项并开启 outDir 和 rootDir：

{
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": []
}

3. 配置 主应用。进入 根目录 app，修改 tsconfig.json。添加 references 字段，指向依赖的子项目：

{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "../packages/core" },
    { "path": "../packages/ui" }
  ]
}

4. 构建 项目。在根目录 运行 tsc --build。
   • TypeScript 会根据依赖关系拓扑排序，先构建 core，再构建依赖它的 ui 和 app。
   • 当只修改了 ui 的代码时，重新运行 tsc --build 只会重新编译 ui 及依赖它的项目，core 会被直接跳过（利用缓存）。

四、 优化代码结构与导入

代码组织方式直接影响编译器的图遍历效率。不当的导入方式会导致编译器加载大量无关文件。

1. 避免 使用 Barrel Files（桶文件/索引文件）进行深层嵌套导入。

   • 不推荐：import { Button } from 'ui'; 如果 ui/index.ts 导出了上百个组件，编译器必须检查所有这些组件的类型。
   • 推荐：import { Button } from 'ui/components/Button';

2. 检查 并 消除 循环依赖。循环依赖会导致类型检查器反复递归验证，严重拖慢速度。

   • 使用 工具如 madge 来检测循环依赖：npx madge --circular --extensions ts src/。

3. 减少 在类型文件中导入庞大的值。

   • 如果只需要类型，确保使用 import type 语法，防止运行时值的引用增加编译负担。

// 正确
import type { UserConfig } from './config';

// 错误（如果只需要类型）
import { UserConfig } from './config';

五、 升级编译工具链

TypeScript 编译器（tsc）本身是为准确性而非极致速度设计的。在开发环境，可以替换为更快的转译工具。

1. 安装 swc (Speedy Web Compiler) 或 esbuild。这些工具使用 Rust 或 Go 编写，速度比 tsc 快 10-100 倍。

npm install -D @swc/core @swc/cli

2. 配置 swc 进行文件转译。创建 .swcrc 文件：

{
  "jsc": {
    "parser": {
      "syntax": "typescript"
    },
    "target": "es2015"
  }
}

3. 修改 package.json 的脚本。将 tsc 替换为 swc 进行开发环境的构建：

{
  "scripts": {
    "dev": "swc src -d dist --watch",
    "type-check": "tsc --noEmit"
  }
}

4. 分离 类型检查与代码生成。
   • 在开发模式下，使用 swc 进行极速转译以获得即时反馈。
   • 在提交代码或 CI/CD 阶段，运行 tsc --noEmit 进行完整的类型检查，确保代码质量。这种组合策略兼顾了开发速度和类型安全。