用途
该技能面向 TypeScript 开发场景,当用户提出编写 TypeScript、配置 TypeScript、定义类型、使用泛型或工具类型等需求时触发。
主要能力
技能内容围绕以下方面展开:
- 严格类型检查:涵盖启用全部严格检查、显式处理 null 与 undefined、更严格的函数类型检查、检查 bind/call/apply、类属性必须初始化、隐式 any 报错、缺失 return 报错、隐式 this 报错、索引签名添加 undefined,以及未使用局部变量和参数报错。
- 模块解析:提供现代 Node.js ESM 解析(nodenext)配置示例,说明需在 package.json 中设置 "type": "module";也给出面向打包工具(Vite、esbuild、webpack)的 bundler 解析示例,以及路径别名配置示例。文中提示 baseUrl 在 TS 6.x 已弃用并预计在 TS 7.x 移除,建议不使用 baseUrl 的 paths;moduleResolution: "node" 在 TS 6.0 已移除,应使用 "nodenext" 或 "bundler"。
- 项目引用:展示 composite、incremental、tsBuildInfoFile 及 references 配置,并说明使用 tsc --build 进行增量编译。
- Node.js 原生 TypeScript:Node.js 24+ 无需标志或外部运行器即可直接运行 TypeScript;Node.js 22.6+ 需要 --experimental-strip-types。运行方式为 node src/index.ts。运行时剥离类型标注,代码需为 "erasable syntax only",避免 enum、namespace、带运行时语义的参数属性。可通过 tsconfig 的 erasableSyntaxOnly 启用兼容性检查。
- 类型模式:列出常用工具类型(可选化、必选化、只读化、键值对象、选取属性、排除属性、联合排除、联合提取、移除非空、取返回类型、取参数元组、解包 Promise);泛型约束、默认类型参数、多约束;条件类型及 infer、分布式条件类型;映射类型及键重映射、按类型过滤;模板字面量类型及参数提取;类型守卫(typeof、instanceof、自定义 is 谓词、in 操作符);branded types;satisfies 操作符;以及从运行时 schema 派生类型、机器可读字段描述、归一化校验结果等做法。
- 运行时模式:Result 类型错误处理、自定义错误、cause 链式错误;using/await using 资源管理(需 lib ESNext.Disposable 或 target ES2024+);Promise.all、allSettled、异步生成器分页;ES 模块导出、barrel exports、动态导入。
- 服务端与客户端边界:在全栈框架中,服务端专属代码(数据库客户端、密钥、node: 模块)不得进入客户端包,应通过打包器能识别的显式边界强制,而不是依赖 tree-shaking。
- 边缘运行时:边缘/隔离运行时(如 Cloudflare Workers)不是 Node.js,没有同步文件系统,import.meta.url 为 undefined,process.env 不是配置来源。
- 认证安全模式:结构性检查而非密码学检查会导致认证失败开放;外部令牌和跨请求 nonce 应视为对抗性输入。
- 六边形端口:将每个外部依赖抽象为端口,每个环境一个适配器;时钟、定时器、随机性也是依赖,应作为端口。
- ESLint 与测试:给出 ESLint 10 的 defineConfig 配置示例,使用 typescript-eslint 的 strictTypeChecked,说明 ESLint 10 从被 lint 文件所在目录定位 eslint.config.*;列出关键规则(no-explicit-any 优先 unknown、no-unused-vars、strict-boolean-expressions、no-floating-promises、prefer-nullish-coalescing)。给出 Vitest 配置示例,说明 Vitest 4 移除 Browser Mode 的实验标签,视觉回归测试可用。
使用方式
技能以配置示例和代码片段形式提供指导,用户可在对应场景中参考这些示例编写 TypeScript 配置与代码。
适用场景
适用于需要编写或配置 TypeScript 项目、处理类型系统与运行时模式、配置代码检查与测试的前端或 Node.js 开发工作。
限制
该技能要求用户具备 TypeScript 基础;部分特性依赖特定版本(如 Node.js 24+、TS 5.2+、TS 6.x/7.x 的变更),需注意版本兼容性。