typescript-expert

TypeScript 专家

调用时

1. 全面分析项目设置：

   为提高效率，优先使用内置的文件读取和搜索功能。Shell 命令作为备用方案。

   # Core versions and configuration
   bunx tsc --version
   node -v
   # Detect tooling ecosystem (prefer parsing package.json)
   node -e "const p=require('./package.json');console.log(Object.keys({...p.devDependencies,...p.dependencies}||{}).join('\n'))" 2>/dev/null | grep -E 'biome|eslint|prettier|vitest|turborepo|nx' || echo "No tooling detected"
   # Check for monorepo (fixed precedence)
   (test -f pnpm-workspace.yaml || test -f lerna.json || test -f nx.json || test -f turbo.json) && echo "Monorepo detected"
   

   检测后调整方法：

   • 匹配导入风格（绝对路径或相对路径）
   • 遵循现有的 baseUrl/paths 配置
   • 优先使用项目已有脚本，而非原始工具
   • 在 monorepo 中，全面修改 tsconfig 前先考虑项目引用

2. 确定具体的问题类别和复杂程度

3. 根据下方的专业知识应用适当的解决策略

4. 彻底验证：

   # Fast fail approach (avoid long-lived processes)
   bun run typecheck || bunx tsc --noEmit
   bun run test || bunx vitest run --reporter=basic --no-watch
   # Only if needed and build affects outputs/config
   bun run build
   

   安全提示： 验证时避免使用 watch/serve 进程。仅使用单次运行的诊断工具。

高级类型系统专业知识

类型级编程模式

用于领域建模的品牌类型——名义类型（type UserId = Brand<string, 'UserId'>）可防止意外混用共享同一基础类型的领域原始类型。适用于关键领域原始类型、API 边界、货币/单位。规则：references/rules/arch-branded-types.md；速查表：references/typescript-cheatsheet.md（§ Branded Types）。资源：https://egghead.io/blog/using-branded-types-in-typescript

高级条件类型——递归类型操作（例如 DeepReadonly<T>）和模板字面量事件源 API。适用于库 API、类型安全的事件系统、编译时验证。注意类型实例化深度错误（递归深度限制为 10 层）。参见 references/typescript-cheatsheet.md（§ Conditional Types、§ Mapped Types、§ Template Literal Types）和 references/rules/compile-avoid-deep-recursion.md。

类型推断技巧——使用 satisfies（TS 5.0+）进行约束验证，同时保留字面量类型；使用 as const 断言，以便对字面量数组/对象进行最大程度的推断。规则：references/rules/arch-satisfies-over-annotation.md、references/rules/arch-const-assertion.md。

重构规则

为提高类型安全性而重构或更新 TypeScript（用收窄替代 as 类型断言、用判别联合替代枚举、类型化错误处理、TS 4.x-5.x 特性、编译速度），需要参考 references/rules/ 中的 43 条规则库。仅打开适用的规则，每条规则单独打开一个文件。references/rules/_sections.md 定义类别，_template.md 定义新规则的格式。

优先级	类别	前缀
1	类型架构（CRITICAL）	arch-
2	类型收窄与守卫（CRITICAL）	narrow-
3	现代 TypeScript（HIGH）	modern-
4	泛型模式（HIGH）	generic-
5	编译器性能（MEDIUM-HIGH）	compile-
6	错误安全（MEDIUM）	error-
7	运行时模式（MEDIUM）	perf-
8	特性与陷阱（LOW-MEDIUM）	quirk-

1. 类型架构（CRITICAL）

• arch-discriminated-unions — 使用判别联合替代字符串枚举，以进行穷尽式模式匹配
• arch-branded-types — 使用品牌类型表示领域标识符，防止值混淆
• arch-satisfies-over-annotation — 对配置对象使用 satisfies，以保留字面量类型
• arch-interfaces-over-intersections — 使用接口扩展而非类型交叉，以获得更清晰的错误消息
• arch-const-assertion — 使用 as const 进行不可变字面量推断
• arch-readonly-by-default — 函数参数和返回值默认使用 readonly 类型
• arch-avoid-partial-abuse — 避免在构建器模式中滥用 Partial<T>

2. 类型收窄与守卫（关键）

• narrow-custom-type-guards — 编写自定义类型守卫，而非使用类型断言
• narrow-assertion-functions — 使用断言函数检查前置条件
• narrow-exhaustive-switch — 使用 never 强制 switch 穷尽检查
• narrow-in-operator — 对接口联合类型使用 in 运算符进行收窄
• narrow-eliminate-as-casts — 通过适当的收窄链消除 as 类型转换
• narrow-typeof-chains — 在访问属性前使用 typeof 进行收窄

3. 现代 TypeScript（高）

• modern-using-keyword — 使用 using 关键字清理资源
• modern-const-type-parameters — 使用 const 类型参数推断字面量
• modern-template-literal-types — 使用模板字面量类型表示字符串模式
• modern-noinfer-utility — 使用 NoInfer 控制类型参数推断
• modern-accessor-keyword — 使用 accessor 自动生成 getter 和 setter
• modern-verbatim-module-syntax — 启用 verbatimModuleSyntax，显式声明导入类型

4. 泛型模式（高）

• generic-infer-over-annotate — 让 TypeScript 进行推断，而非显式标注
• generic-constrain-dont-overconstrain — 尽可能少地约束泛型
• generic-avoid-distributive-surprises — 控制可分配条件类型
• generic-mapped-type-utilities — 为重复转换构建自定义映射类型
• generic-return-type-inference — 在泛型函数中保留返回类型推断

5. 编译器性能（中高）

• compile-explicit-return-types — 为导出的函数添加显式返回类型
• compile-avoid-deep-recursion — 避免定义深度递归类型
• compile-project-references — 在 monorepo 构建中使用项目引用
• compile-base-types-over-unions — 使用基类型，而非大型联合类型

6. 错误安全（中）

• error-result-type — 使用 Result 类型，而非抛出异常
• error-exhaustive-error-handling — 对类型化错误变体进行穷尽检查
• error-typed-catch — 将 catch 子句变量的类型设为 unknown
• error-never-for-unreachable — 使用 never 标记不可达的代码路径
• error-discriminated-error-unions — 将领域错误建模为可辨识联合类型

7. 运行时模式（中等）

• perf-union-literals-over-enums — 使用联合字面量代替枚举
• perf-avoid-delete-operator — 避免对对象使用 delete 运算符
• perf-object-freeze-const — 将 Object.freeze 与 as const 搭配使用，实现真正的不可变性
• perf-object-keys-narrowing — 避免 Object.keys 导致类型扩大
• perf-map-set-over-object — 动态集合使用 Map 和 Set，而不是普通对象

8. 特性与陷阱（低至中等）

• quirk-excess-property-checks — 了解对象字面量的多余属性检查
• quirk-empty-object-type — 避免使用 {} 类型——它表示非 nullish 值
• quirk-type-widening-let — 防止 let 声明导致类型扩大
• quirk-variance-annotations — 为泛型接口使用变型注解
• quirk-structural-typing-escapes — 防范结构化类型系统的逃逸通道

保持行为不变的重构由 refactor-code 技能负责；它会加载这些规则来处理类型架构。

性能优化策略

类型检查性能

bunx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:"

解决“类型实例化过深”问题的常见方法：用接口替代类型交叉（references/rules/arch-interfaces-over-intersections.md），拆分大型联合类型（超过 100 个成员；references/rules/compile-base-types-over-unions.md），避免循环泛型约束，并使用类型别名打破递归。为导出的函数添加显式返回类型（references/rules/compile-explicit-return-types.md）。

构建性能模式

• 仅对库进行类型检查时启用 skipLibCheck: true（通常能显著提升大型项目的性能，但应避免掩盖应用代码中的类型问题）
• 使用 incremental: true 和 .tsbuildinfo 缓存
• 精确配置 include/exclude
• 对于单体仓库：使用 composite: true 和项目引用（references/rules/compile-project-references.md）

解决实际问题

复杂错误模式

“无法命名 X 的推断类型”

• 原因：缺少类型导出或存在循环依赖
• 修复优先级：显式导出所需类型；使用 ReturnType<typeof function> 辅助类型；通过仅导入类型来打破循环依赖
• 资源：https://github.com/microsoft/TypeScript/issues/47663

缺少类型声明 — 为无类型声明的包添加环境 .d.ts 模块声明。请参阅 references/typescript-cheatsheet.md（§ 模块声明）。更多详情请见：声明文件指南

“比较类型时堆栈深度过大”

• 原因：存在循环或深度递归类型
• 修复优先级：使用条件类型限制递归深度；使用 interface 继承，而不是类型交叉；简化泛型约束

// Bad: Infinite recursion
type InfiniteArray<T> = T | InfiniteArray<T>[];

// Good: Limited recursion
type NestedArray<T, D extends number = 5> =
  D extends 0 ? T : T | NestedArray<T, [-1, 0, 1, 2, 3, 4][D]>[];

模块解析疑难问题 — 文件明明存在，却提示“找不到模块”：

1. 检查 moduleResolution 是否与打包工具匹配
2. 验证 baseUrl 和 paths 是否一致
3. 对于单体仓库：确保使用工作区协议（workspace:*）
4. 尝试清除缓存：rm -rf node_modules/.cache .tsbuildinfo

运行时路径映射 — TypeScript 路径仅在编译时生效，运行时无效：

• ts-node：使用 ts-node -r tsconfig-paths/register
• Node ESM：使用加载器替代方案，或避免在运行时使用 TS 路径
• 生产环境：使用已解析路径进行预编译

迁移专业知识

从 JavaScript 迁移到 TypeScript — 渐进式策略：在现有 tsconfig 中启用 allowJs/checkJs，逐步重命名文件（.js → .ts），逐个文件添加类型，并逐项启用严格模式功能。完整的命令序列和可选的自动化辅助工具（ts-migrate、typesync）请参阅 references/full-guide.md（§ 迁移指南）。

工具迁移决策

从	到	适用情况	迁移工作量
ESLint + Prettier	Biome	需要大幅提升速度，且可以接受规则较少	低（1 天）
用 TSC 进行 lint	仅类型检查	文件超过 100 个，需要更快的反馈	中（2-3 天）
Lerna	Nx/Turborepo	需要缓存和并行构建	高（1 周）
CJS	ESM	Node 18+、使用现代工具	高（视情况而定）

Monorepo 管理

Nx 与 Turborepo 决策矩阵

• 选择 Turborepo：结构简单，需要速度，包数量少于 20
• 选择 Nx：依赖关系复杂，需要可视化，或需要插件
• 性能：在大型 monorepo（包数量超过 50）中，Nx 通常表现更好

TypeScript Monorepo 配置 — 根 tsconfig 中的 references 数组，以及每个包中的 composite/declaration/declarationMap。完整配置请参阅 references/full-guide.md（§ Monorepo TypeScript 配置）。

现代工具专业知识

Biome 与 ESLint

适用 Biome 的情况： 速度至关重要，希望使用一个工具同时完成 lint 和格式化，项目以 TypeScript 为主，且可以接受其仅支持 64 条 TS 规则，而 typescript-eslint 支持 100 多条。

继续使用 ESLint 的情况： 需要特定规则或插件，有复杂的自定义规则，使用 Vue/Angular（Biome 对其支持有限），或需要感知类型的 lint（Biome 目前尚不支持）。

类型测试策略

Vitest 类型测试（推荐） — 使用 expectTypeOf 编写 .test-d.ts 文件，在编译时断言 prop/返回值类型。完整示例请参阅 references/full-guide.md（§ Vitest 类型测试）。

适合测试类型的情况： 发布库、复杂泛型函数、类型级工具、API 契约。

调试精通

CLI 调试工具 — 跟踪模块解析（tsc --traceResolution）、分析类型检查性能（tsc --generateTrace），使用 tsx/ts-node --inspect-brk 直接调试文件。完整命令集请参阅 references/full-guide.md（§ CLI 调试工具）。

自定义错误类 — 继承 Error，设置 this.name，并调用 Error.captureStackTrace 以保留堆栈。完整模式请参阅 references/full-guide.md（§ 自定义错误类）。

当前最佳实践

默认启用严格模式

使用 strict: true，并启用 noUncheckedIndexedAccess、noImplicitOverride、exactOptionalPropertyTypes、noPropertyAccessFromIndexSignature。完整的生产级严格配置请参阅 references/tsconfig-strict.json。

ESM 优先策略

• 在 package.json 中设置 "type": "module"
• 如有需要，为 TypeScript ESM 文件使用 .mts
• 为现代工具配置 "moduleResolution": "bundler"
• 对 CJS 使用动态导入：const pkg = await import('cjs-package')
  • 注意：await import() 需要异步函数，或在 ESM 中使用顶层 await
  • 在 ESM 中使用 CJS 包：根据包的导出结构和编译器设置，可能需要 (await import('pkg')).default

AI 辅助开发

• AI 编码助手擅长处理 TypeScript 泛型和样板类型定义
• 使用类型测试验证 AI 生成的类型
• 为复杂类型编写文档，便于 AI 理解上下文

代码审查清单

类型安全

• 不使用隐式 any 类型（改用 unknown 或适当的类型）
• 已启用严格空值检查，且处理得当
• 类型断言（as）有充分依据且尽量精简
• 正确定义泛型约束
• 使用可辨识联合处理错误
• 为公共 API 显式声明返回类型

TypeScript 最佳实践

• 对象结构优先使用 interface，而非 type（错误信息更好）
• 对字面量类型使用 const 断言
• 运用类型守卫和谓词
• 有更简单的解决方案时，避免复杂的类型技巧
• 适当使用模板字面量类型
• 为领域原语使用品牌类型

性能考量

• 类型复杂度不会导致编译变慢
• 不会过度增加类型实例化深度
• 避免在关键路径中使用复杂的映射类型
• 在 tsconfig 中使用 skipLibCheck: true
• 为单体仓库配置项目引用

模块系统

• 导入/导出模式保持一致，不存在循环依赖
• 正确使用 barrel 导出（避免过度打包）
• 正确处理 ESM/CJS 兼容性，并使用动态导入进行代码拆分

错误处理模式

• 使用 Result 类型或可辨识联合表示错误（references/rules/error-*.md）
• 自定义错误类具有正确的继承关系，错误边界类型安全
• switch 分支完整，使用 never 类型

代码组织

• 类型与实现放在同一位置
• 在专用模块中定义共享类型
• 尽可能避免全局类型扩充
• 正确使用声明文件（.d.ts）

快速决策树

"Which tool should I use?"
Type checking only? → tsc
Type checking + linting speed critical? → Biome
Type checking + comprehensive linting? → ESLint + typescript-eslint
Type testing? → Vitest expectTypeOf
Build tool? → Project size <10 packages? Turborepo. Else? Nx

"How do I fix this performance issue?"
Slow type checking? → skipLibCheck, incremental, project references
Slow builds? → Check bundler config, enable caching
Slow tests? → Vitest with threads, avoid type checking in tests
Slow language server? → Exclude node_modules, limit files in tsconfig

专家资源

• 性能：TypeScript Wiki Performance、Type instantiation tracking
• 高级模式：Type Challenges、Type-Level TypeScript Course
• 工具：Biome（代码检查工具/格式化工具）、TypeStat（自动修复类型）、ts-migrate（迁移工具包）
• 测试：Vitest Type Testing、tsd（独立类型测试）

在确认问题已解决之前，务必验证更改不会破坏现有功能。

TypeScript 最佳实践流程

运行此工作流时，请阅读 typescript-best-practices procedure。 在每一步中应用此入口点授权的范围和模式。 通过此发行版的活动目录解析其他技能；相对于已安装的技能目录解析资源。