typescript

用途

本技能是一份兼容 TypeScript 7 的 TypeScript 最佳实践指南，包含 8 个类别共 44 条规则，覆盖编译器配置、类型系统性能、异步代码、模块组织、类型安全、内存管理与可测量的运行时优化。

何时适用

在以下情况参考这些指南：

为新项目或现有项目配置 tsconfig.json
编写复杂类型定义或泛型
优化 async/await 模式与数据获取
组织模块与管理导入
审查代码的编译或运行时性能

规则类别（按优先级）

优先级	类别	影响	前缀
1	类型系统性能	CRITICAL	type-
2	编译器配置	CRITICAL	tscfg-
3	异步模式	HIGH	async-
4	模块组织	HIGH	module-
5	类型安全模式	MEDIUM-HIGH	safety-
6	内存管理	MEDIUM	mem-
7	运行时优化	LOW-MEDIUM	runtime-
8	高级模式	LOW	advanced-

1.1 为导出函数添加显式返回类型 — CRITICAL（更快的声明生成）
1.2 避免深度嵌套的泛型类型 — CRITICAL（防止指数级实例化开销）
1.3 避免大型联合类型 — CRITICAL（二次方 O(n²) 比较开销）
1.4 将条件类型提取为具名别名 — CRITICAL（启用编译器缓存，防止重复求值）
1.5 限制类型递归深度 — CRITICAL（防止指数级类型展开）
1.6 优先使用接口而非类型交叉 — CRITICAL（更快的类型解析）
1.7 简化复杂的映射类型 — CRITICAL（减少类型计算）

编译器配置 — CRITICAL

2.1 正确配置 include 与 exclude — CRITICAL（防止扫描数千个不必要的文件）
2.2 启用增量编译 — CRITICAL（更快的重建）
2.3 审慎选择 skipLibCheck — CRITICAL（更快的编译）
2.4 启用 strictFunctionTypes 以获得健全的函数赋值 — CRITICAL（启用优化的变异性检查）
2.5 为单文件转译器使用 isolatedModules — CRITICAL（配合打包器实现更快的转译）
2.6 为大型代码库使用项目引用 — CRITICAL（更快的增量构建）
2.7 审慎迁移 TypeScript 7 配置 — CRITICAL

异步模式 — HIGH

3.1 标注异步函数返回类型 — HIGH（防止运行时错误，改善推断）
3.2 避免在循环内使用 await — HIGH（随迭代次数线性增长）
3.3 避免不必要的 async/await — HIGH（消除微任务队列开销）
3.4 延迟 await 直到需要该值 — HIGH（实现隐式并行化）
3.5 对独立操作使用 Promise.all — HIGH（改善 I/O 密集型代码）

模块组织 — HIGH

4.1 避免桶文件导入 — HIGH（导入开销，更大的打包体积）
4.2 避免循环依赖 — HIGH（防止运行时 undefined 错误与缓慢编译）
4.3 控制 @types 包的引入 — HIGH（防止类型冲突并减少内存占用）
4.4 对大型模块使用动态导入 — HIGH（减小初始包体积）
4.5 对类型使用仅类型导入 — HIGH（消除类型信息的运行时导入）

类型安全模式 — MEDIUM-HIGH

5.1 启用 strictNullChecks — MEDIUM-HIGH
5.2 优先使用 unknown 而非 any — MEDIUM-HIGH
5.3 使用断言函数进行校验 — MEDIUM-HIGH
5.4 使用 const 断言获得字面量类型 — MEDIUM-HIGH
5.5 对联合类型使用穷尽检查 — MEDIUM-HIGH
5.6 使用类型守卫进行运行时类型检查 — MEDIUM-HIGH

内存管理 — MEDIUM

6.1 避免闭包内存泄漏 — MEDIUM（防止长生命周期回调中保留引用）
6.2 避免全局状态累积 — MEDIUM（防止无界内存增长）
6.3 清理事件监听器 — MEDIUM（防止无界内存增长）
6.4 清除定时器与间隔 — MEDIUM（防止回调保留与重复执行）
6.5 使用 WeakMap 存储对象元数据 — MEDIUM（防止内存泄漏，实现自动清理）

运行时优化 — LOW-MEDIUM

7.1 避免在热循环中使用对象展开 — LOW-MEDIUM
7.2 在可测量的热路径中提升循环不变量 — LOW-MEDIUM
7.3 优先使用原生数组方法而非 Lodash — LOW-MEDIUM
7.4 使用 for-of 进行简单迭代 — LOW-MEDIUM
7.5 使用现代字符串方法 — LOW-MEDIUM
7.6 使用 Set/Map 实现 O(1) 查找 — LOW-MEDIUM

高级模式 — LOW

8.1 使用品牌类型实现类型安全的 ID — LOW（防止混用不兼容的 ID 类型）
8.2 使用 satisfies 进行带推断的类型校验 — LOW（防止属性访问错误，启用可靠的自动补全）
8.3 使用模板字面量类型处理字符串模式 — LOW（在编译期防止字符串格式错误）

如何使用

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect                   # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill typescript  # deprecated APIs → rule IDs

针对上述每条与任务匹配的规则以及每个扫描命中项，阅读 references/<rule-id>.md：其中说明为何重要，以及错误与正确代码的对比。

参考资料

https://github.com/microsoft/TypeScript/wiki/Performance
https://www.typescriptlang.org/docs/handbook/
https://v8.dev/blog
https://nodejs.org/en/learn/diagnostics/memory

技能介绍

用途

何时适用

规则类别（按优先级）

目录

类型系统性能 — CRITICAL

编译器配置 — CRITICAL

异步模式 — HIGH

模块组织 — HIGH

类型安全模式 — MEDIUM-HIGH

内存管理 — MEDIUM

运行时优化 — LOW-MEDIUM

高级模式 — LOW

如何使用

参考资料