TypeScript · tsconfig 与构建链路

场景 1 · 上线后才炸的类型错误: 补 CI 双门禁

vite build 全绿, 上线后 optional chaining 用在 number 上崩了。根因: 从没人跑过 tsc:

# .github/workflows/ci.yml
- run: pnpm typecheck    # tsc --noEmit
- run: pnpm test
- run: pnpm build        # vite build
# 本地 husky pre-push 也跑 typecheck, 双保险

上线首周抓出 17 个被转译器吞掉的类型错误。

场景 2 · 老仓库渐进开 strict: 分目录双 tsconfig

12 万行旧代码开 strict 等于停摆三个月。新代码 strict, 旧代码维持, 边界渐进推进:

// tsconfig.json (基础, 不开 strict)
{ "extends": "./tsconfig.base.json", "include": ["src-old"] }
// tsconfig.strict.json
{ "extends": "./tsconfig.base.json",
  "compilerOptions": { "strict": true },
  "include": ["src-new"] }
// CI: 新目录强制, 旧目录每季度迁移 10%

场景 3 · monorepo 增量构建: project references

20 个包每次全量检查 6 分钟。references + composite 后只重查被改的包链:

// 根 tsconfig.json
{ "files": [],
  "references": [
    { "path": "packages/core" },
    { "path": "packages/ui" },
    { "path": "apps/web" } ] }
# tsc -b  ← 按依赖拓扑增量构建

全量 6min → 增量 40s。

场景 4 · 别名 404: paths 与打包器双配

tsc 检查通过, vite dev 却报 cannot resolve '@/lib/x'。tsconfig paths 只对 tsc 生效:

// vite.config.ts 必须同步:
import { fileURLToPath } from 'node:url';
export default {
  resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
};
// jest 侧还要 moduleNameMapper — 每个工具各配一次

场景 5 · 库发布: d.ts 从源码生成而非手写

手写声明与实现漂移, 用户编译报错但运行正常, 售后噩梦。改为声明自动生成:

{ "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist" },
  "include": ["src"] }
// package.json: "types": "./dist/index.d.ts"
// CI: 消费侧 tsc 编译通过作为发布门槛

场景 6 · skipLibCheck 提速与风险并存

全量检查 90s, 其中 70s 在检查 node_modules 的 .d.ts。开启后 20s, 但要单独守护自家声明:

{ "skipLibCheck": true }
// 库项目额外跑一次不带 skip 的检查自家 d.ts:
// tsc --noEmit --skipLibCheck false dist/index.d.ts
// 锁定关键依赖的类型版本(package-lock)防漂移

场景 7 · isolatedModules 修正存量代码

开启后 barrel 里裸类型 re-export 全部报错。批量改成显式 type 导出:

// 错: export { User, Order } from './types';
// 对: export type { User, Order } from './types';
// const enum 同理被禁 → 换 as const 对象:
const Kind = { a: 'a' } as const;
type Kind = typeof Kind[keyof typeof Kind];

场景 8 · target 选型: 语法降级与 polyfill 边界

target ES5 导致 ?? 可选链全转译, 产物肥 30%; 但只调 target 不够, polyfill 是另一层:

{ "target": "ES2020" }   // 保留 ?? 与 ?., 现代浏览器直跑
// 老浏览器兼容交给 @vitejs/plugin-legacy / core-js:
// polyfill 由打包器注入, ts target 只管语法降级

产物 -28%, Lighthouse 脚本解析时间同步下降。

场景 9 · ESM/CJS 双构建的 tsconfig 组合

库要双格式输出, 用两个 tsconfig 各自 emit, exports 字段分流:

// tsconfig.esm.json: module ESNext, outDir dist/esm
// tsconfig.cjs.json: module CommonJS, outDir dist/cjs
# tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json
// package.json exports: { import: dist/esm, require: dist/cjs }

场景 10 · 类型检查内存爆炸: fork 化 + 缓存

大仓 tsc 峰值 6GB, IDE 卡死。方案: 分项目 references + CI 缓存 + 必要时 fork:

# webpack 项目: thread 化类型检查
ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
// vite 项目: vite-plugin-checker 同理, 不阻塞转译主进程
// NODE_OPTIONS=--max-old-space-size=8192 tsc --noEmit