TypeScript 构建性能优化：增量编译、缓存与工具链选型

tsc 编译 = 类型检查（慢）+ 转译（快）

类型检查：解析整个类型图、推导、报错 → O(项目大小)，是大头
转译     ：去掉类型、生成 JS → 相对快

优化思路：把两者拆开——
  转译用快工具（esbuild/swc），类型检查单独跑（且尽量增量/缓存）

1. 每次全量解析所有文件（无记忆）
2. 类型检查是全程序分析（依赖图）
3. 装饰器/高级类型更慢
4. 大项目（数千文件）指数放大

手段：
  1. incremental：tsc 记住上次结果（增量）
  2. 转译器替换：esbuild/swc（快 10-100 倍）
  3. 项目引用：按依赖图只编译变更的包
  4. monorepo 缓存：Turborepo 缓存未变任务
  5. 类型检查独立：开发时跳过 typecheck，CI 再全量

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./node_modules/.cache/tsconfig.tsbuildinfo"
  }
}

tsc 把「上一次的编译信息」存到 .tsbuildinfo
下次只重新检查「变更文件及其依赖」→ 大幅提速

适用：本机开发、重复 typecheck
局限：CI 每次是干净环境 → 缓存要持久化（CI cache 或 monorepo 缓存）

# .gitignore 里排除
node_modules/.cache/
*.tsbuildinfo

# CI 缓存 tsbuildinfo
- uses: actions/cache@v4
  with:
    path: node_modules/.cache
    key: tsc-${{ hashFiles('src/**/*.ts') }}

大项目拆成多个子项目：每个有自己的 tsconfig + 依赖声明
tsc 只构建「变更的子项目 + 依赖它的」→ 按依赖图增量

// tsconfig.base.json
{
  "compilerOptions": {
    "composite": true,          // 子项目必须开
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

// apps/web/tsconfig.json —— 引用共享包
{
  "compilerOptions": { "composite": true },
  "references": [
    { "path": "../../packages/ui" },
    { "path": "../../packages/types" }
  ]
}

composite 强制：declaration 开启、rootDir 明确、noEmit 不能开
构建顺序：tsc -b（build 模式）自动按 references 拓扑排序

# 构建所有引用项目（按依赖顺序）
tsc -b apps/web packages/ui packages/types

# 只构建变更的
tsc -b apps/web --watch

1. 大型 Monorepo：包按依赖图增量编译
2. 前后端共享类型：类型包单独编译，引用方直接消费 d.ts
3. CI 中按 affected 构建

esbuild/swc 按「单文件」转译（不做全程序类型分析）
某些 TS 语法需要「全局信息」才能正确转译：
  - 重导出类型（import { T } / export { T }）可能被误删
  - 命名空间合并
isolatedModules 强制代码「可单文件编译」，避免转译器误删类型

{
  "compilerOptions": {
    "isolatedModules": true,
    "verbatimModuleSyntax": true   // 显式区分 type/值导入
  }
}

import type { UserDTO } from './types'   // 明确是类型 → 转译器安全删除
import { getUser } from './api'          // 值是值 → 保留

export type { UserDTO }                  // 类型重导出，安全

// 反例：值导入误当类型用，转译器可能误判
import { UserDTO } from './types'   // UserDTO 是类型 → 用 import type
// 反例：export 类型时混在值里
export { UserDTO } from './types'   // 应 export type { UserDTO }

# 开发：esbuild 转译（秒级）
esbuild src/index.ts --bundle --outfile=dist/index.js --platform=node

# 类型检查：单独跑（增量）
tsc --noEmit --incremental

// build.ts（脚本化）
import { build } from 'esbuild'

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  platform: 'node',
  sourcemap: true,
  target: 'es2022',
})

# tsup 默认用 esbuild，可配置 typecheck
npx tsup src/index.ts --dts --sourcemap

// tsup.config.ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,             // 生成 .d.ts（内部用 tsc）
  sourcemap: true,
  clean: true,
})

开发构建/打包  → esbuild（Go，最快）或 swc（Rust，Next.js 默认）
库发布        → tsup（esbuild + dts）
类型检查      → 永远用 tsc（转译器不做类型检查）
关键：转译器负责「快」，tsc 负责「准」，两者分离

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "cache": true
    },
    "typecheck": { "cache": true }
  }
}

pnpm turbo build          # 未变包命中缓存
pnpm turbo typecheck      # 类型检查也缓存

缓存键 = 源码哈希 + 配置 + 依赖锁定文件
未变 → 直接取上次产物（秒级）
远程缓存（Turborepo Remote Cache）→ CI 与本地共享

1. 依赖顺序：dependsOn ^build 保证先构建依赖
2. 内存限制：并行度过高会 OOM → 限制 --concurrency
3. 缓存失效：环境变量/路径别名变化会清缓存

ts-loader：每次全量类型检查（慢）
babel-loader：只转译不检查（快），类型检查交给 fork-ts-checker
esbuild-loader / swc-loader：更快

最佳实践：
  babel-loader / swc-loader（转译）+ fork-ts-checker（后台类型检查）

Vite 开发：esbuild 转译（秒级热更新），不做类型检查
类型检查：单独 script 跑 vue-tsc / tsc --noEmit

{
  "scripts": {
    "dev": "vite",                       // esbuild 转译
    "build": "tsc --noEmit && vite build" // 先检查再构建
  }
}

开发：转译器秒级（跳过 typecheck）→ 体验快
CI/发布：tsc --noEmit 全量检查 → 质量保底
折中：本地用 vite-tsc / fork-ts-checker 后台检查

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

作用：跳过 .d.ts 文件的类型检查（只检查业务代码）
收益：显著提速（node_modules 类型不重复查）
风险：node_modules 内类型错误不报 → 一般可接受（第三方错误非你可控）
推荐：生产项目开启

// tsconfig paths
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@app/*": ["src/*"] }
  }
}

影响：
  1. 转译器（esbuild/swc）需插件才能解析 paths（别名）
  2. 打包器（webpack/vite）各自配 resolve.alias
  3. 生成 .d.ts 时 paths 要能正确映射（否则类型引用错）
实践：paths 只在源码层用，产物层用相对路径/包名

{
  "compilerOptions": {
    "skipLibCheck": true,
    "noEmit": true,          // 只检查不产出（CI typecheck）
    "incremental": true,
    "types": []              // 只加载需要的 @types（减少全局）
  }
}

# 量化
time npx tsc --noEmit
time pnpm turbo build --dry-run   # 看缓存命中

1. tsc 慢 → 检查 skipLibCheck / incremental / 项目引用
2. 打包慢 → 检查是否重复类型检查（ts-loader）→ 换 swc/babel
3. 特定文件慢 → 装饰器/巨型类型/循环引用
4. 缓存不命中 → 检查缓存键（环境变量/路径）

CI 记录构建/typecheck 时长 → 超阈值告警
定期清理：无引用文件、any 堆积、巨型 d.ts
用 trace（tsc --traceResolution / --generateTrace）深挖