TypeScript 工具链
强制要求
TypeScript 和 Python 是 AI 辅助开发的默认语言,因为它们的库生态和 AI Agent 生态最成熟。
语言优先级:
- 产品与全栈开发默认使用 TypeScript。
- Python 仅用于 Python 工具链 列出的适用场景。
- Go 与 Rust 仅用于性能关键或系统级场景;采用前必须说明理由、征得用户批准,并记录在项目 ADR 中。详见 Go 与 Rust。
框架选型见 前端框架:Vite 与 Next.js。
版本策略
使用最新稳定版 TypeScript 和 Active LTS 线上的最新稳定版 Node.js。
截至 2026-08,Active LTS 版本线为 Node.js 24(EOL 2028-04);Node.js 22 处于维护期(EOL 2027-04),Node.js 26 在 2026-10 之前仍是 Current 线。绝不以 Current 线为目标;只有新的 LTS 版本线稳定后,才升级 Node 主版本。
模型根据训练数据生成代码,因此主流且经过充分验证的版本在 AI 辅助开发中出错更少;应优先选择这些版本,而不是追求微小的收益。该原则见 核心工程原则。
在项目的 mise 配置中固定 Node.js 的版本;TypeScript 的版本通过 pnpm lockfile 固定,两者都不依赖全局安装的版本。
pnpm
使用 pnpm。这条要求同时适用于普通 Node.js 项目和 monorepo。
在 mise.toml 中固定 pnpm 版本时,应使用最新版本并通过 mise(mise latest pnpm)查询。注意:npm 中的 pnpm latest 是 11,但实际最新版本是 12。
外部文档给出 npm 或 yarn 命令时,将其改写为 pnpm 等价命令,不要引入其他包管理器。
项目 lockfile 必须与 pnpm 保持一致。
不采用的替代方案
禁止使用:
- npm
- yarn
oxlint
oxlint 是 TypeScript / JavaScript 的标准 Lint 工具。
当框架、模板或库推荐 ESLint 时:
- 弄清它依赖哪些 ESLint 规则或插件。
- 判断 oxlint 是否支持所需功能。
- 只要可行,就使用 oxlint 提供的等效功能。
- 不要仅因模板生成了 ESLint 就保留它。
除非存在具体的兼容性问题,否则使用最新稳定版 oxlint。
规则配置
有针对性地配置 oxlint:根据代码实际运行的环境开启规则和插件,不要只用默认配置,也不要因为脚手架模板没开就漏掉有用的检查。
对于运行在 Node.js 上的代码,在 .oxlintrc.json 中启用 node 插件并开启相关规则(包括防范旧式 CommonJS 写法的规则),同时关闭与项目定位冲突的限制规则(例如,有意同步读写文件的 CLI 工具应保持 no-sync 关闭)。
Type-Aware 与类型检查规则
在项目需要时,启用 oxlint 官方支持的 TypeScript 类型感知(type-aware)Lint 和类型检查。
将配套包 oxlint-tsgolint 与新版 oxlint 一起安装,并在根目录 .oxlintrc.json 中开启 options.typeAware 和 options.typeCheck(截至 2026-08,typeCheck 仍为实验特性)。
参照 oxlint 当前官方文档配置,不要从旧项目照搬过时配置;只要 oxlint 能满足需求,就不要为了类型感知规则再引入 ESLint。
不采用的替代方案
禁止将 ESLint 作为默认 Lint 体系。
oxfmt
oxfmt 是 TypeScript / JavaScript 项目的标准格式化工具。
除非存在具体的兼容性问题,否则使用最新稳定版 oxfmt。
不要对同一组源文件运行多个相互竞争的格式化工具。
不采用的替代方案
禁止使用 Prettier。
tsconfig 基线
每个项目从严格的 tsconfig 基线起步:
"strict": true——严格模式的基础;除非有 ADR 级别的理由,否则不得关闭任何单独的严格性标志。"noUncheckedIndexedAccess": true——索引访问结果为T | undefined,必须处理undefined情况。"verbatimModuleSyntax": true——仅用于类型的导入必须使用import type,避免意外产生运行时导入。"isolatedModules": true——每个文件必须能独立编译,与打包器和转译器的实际处理方式一致。- 只用 ESM。应用项目使用
"module": "ESNext"配"moduleResolution": "Bundler";Node 库使用"module": "NodeNext"配"moduleResolution": "NodeNext"。 - 应用项目不让 tsc 生成输出:设置
"noEmit": true,由打包器生成产物。
基线示例:
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"verbatimModuleSyntax": true,
"isolatedModules": true,
"module": "ESNext",
"moduleResolution": "Bundler",
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"noEmit": true,
},
}
语言使用规则
- 值的类型未知时使用
unknown而不是any,先收窄类型再使用。仅在确实需要动态互操作时使用any,并附注释说明理由。 - 非空断言(
!)必须附注释,说明为什么该值在此处不可能为 null 或 undefined。 - 导出函数显式声明返回类型。
- 使用可辨识联合(discriminated union)为状态建模,不要堆叠一组布尔标志。
- 用
satisfies校验配置对象:错误会在定义处暴露,同时保留字面量类型。 - 字面量表加上
as const,使元素类型保持精确。 - 用联合类型或
const对象代替enum。 - 不留悬空 promise:要么
await,要么有意用void丢弃,并附注释说明为何忽略结果。 - 只能抛出 Error 子类;禁止抛出字符串或普通对象。
项目约定
- 应用源码放在
src/下,入口通过package.json暴露。 - 文件名使用 kebab-case(
user-profile-card.tsx),值使用 camelCase,类型、组件和类使用 PascalCase。 - 避免桶文件(barrel file,即用
index.ts转发整个目录),直接从定义模块导入。桶文件会损害 tree-shaking,还容易造成循环导入。