主题 / 语言
TypeScript / JavaScript / Node 的语言层约定：运行时版本策略、包管理器与锁文件、tsconfig 严格选项、模块格式、lint 与格式化、单元测试与属性测试、运行时校验，以及查询层、迁移工具和 OpenAPI 生成器的选型。
packageManager 写精确版本。依赖的安装脚本默认不执行，只放行白名单；开启发布冷却期。strict 显式写出来。 TypeScript 7（Go 原生编译器）已经发布，默认值也变了，靠默认值不可靠。再加上 noUncheckedIndexedAccess、verbatimModuleSyntax 等。.ts 只是把类型擦掉，不做类型检查；esbuild、tsx、Vite 也一样。CI 必须单独跑 tsc --noEmit。as 糊过去。exports 声明入口。await）时，再加 typescript-eslint，但只用它的类型规则，格式化仍只归一个工具。node --version 并对照官方发布计划；容器镜像扫描标出停止维护的运行时pnpm install --frozen-lockfile 或 npm ci）engines 声明支持的 Node 范围，用 packageManager 写包管理器的精确版本本机用 mise 等版本管理工具读取同一份声明，不在多个地方各写一遍。
latest 版本的工具，不用 npx 包名@latest 这类不锁版本的调用@latest、npm install -g 和不带版本的 npx，评审确认strictDepBuilds 开启，用 allowBuilds 列白名单；CI 检查没有 dangerouslyAllowAllBuilds；白名单文件写进 CODEOWNERS--ignore-scripts 安装，再对需要编译的包单独执行。minimumReleaseAge 没有被设为 0；例外写进 minimumReleaseAgeExclude 并经评审npm pack 打包，在一个干净的项目里安装，验证导入、类型和最低支持的 Node 版本exports 写错只有在真实消费方那里才暴露。strict 为 true，不靠默认值；不得为了通过检查关掉 strict 的子项tsc --showConfig）里 strict 为 true，且没有把 strictNullChecks 等子项设为 falsenoUncheckedIndexedAccess、noImplicitOverride、noFallthroughCasesInSwitch、verbatimModuleSyntax，并显式写 typestypes 在新版中默认不再自动包含所有 @types 包，Node 项目写 ["node"]，测试目录按需补测试库的类型。exactOptionalPropertyTypes 更严格，存量项目开启改动面大，可按模块逐步开。skipLibCheck: true 以控制检查时间，但要知道它会跳过依赖的声明文件错误。tsc --noEmit）；Node 直接运行 .ts、esbuild、tsx、Vite 编译成功都不算类型通过erasableSyntaxOnly 和 verbatimModuleSyntax，不用 enum、带运行时代码的 namespace、参数属性，类型导入写 import typetsc --noEmit 会直接报出不可擦除的语法和缺少 type 的类型导入type 的类型导入会被当成值导入，运行时失败。paths 别名、target 等设置对它无效；也不会处理 node_modules 里的 .ts 文件。as const 对象加联合类型；参数属性改成显式字段赋值。exclude 把它们排除在外tsc --listFilesOnly 的输出包含测试和脚本目录；需要不同设置时用单独的 tsconfig 并在 CI 里一起检查any、非空断言 ! 和 as 绕过类型错误；必须抑制时用 @ts-expect-error 写明原因，禁用 @ts-ignore 和 @ts-nochecknoExplicitAny、noNonNullAssertion，typescript-eslint 的 ban-ts-comment 等）；例外按 02 的要求写理由未知结构的数据用 unknown 接住，再经校验收窄；生成的代码目录可以在专门的例外配置里排除。
as 声明类型JSON.parse 或 response.json() 后直接 as、typescript-eslint 的 no-unsafe-* 规则）；评审检查每个入口都有 schema 解析process.envprocess.env（如 Biome 的 noProcessEnv 或 ESLint 的 n/no-process-env）"type": "module"；Node 直接运行的代码用 NodeNext 模块解析，相对导入写文件扩展名tsc --noEmit 在 NodeNext 下会报出缺扩展名的相对导入./x.ts 时，用 rewriteRelativeImportExtensions 让编译输出变成 ./x.js。bundler 模块解析，见 07。paths 别名在运行时生效；需要内部别名时用 package.json 的 imports（以 # 开头的子路径导入）paths；有的话在评审时确认运行时有对应的解析方式exports 字段声明入口和类型文件；确有 CJS 使用方时才发布双格式exports；双格式包要说明使用方并在 TS-008 的打包测试里覆盖两种导入biome ci .（或用 Prettier 的项目运行 prettier --check .）；检查没有同时配置第二个格式化工具void 标记并处理错误；用 lint 的漏 await 规则检查no-floating-promises 和 no-misused-promises（或 Biome 的对应规则，覆盖不全时见 TS-022）fetch 和客户端库调用是否带 signal；lint 找出没有 signal 参数的 fetch 作为候选AbortSignal.timeout(ms) 只负责产生取消信号，被调用的库忽略 signal 时依然会挂住，选库时要确认它支持取消。
Promise.all(items.map(...))Promise.all；用 p-limit 等库限制并发一个失败就该终止全部时，失败后调用 abort() 取消其余任务；需要收集全部结果时用 Promise.allSettled。
spawn、execFile），不把含外部输入的字符串交给 shell（exec、shell 设为 true）exec、execSync 和 shell 设为 true 的调用，评审确认参数不含外部输入子进程要限制运行时间和输出大小，并在退出或取消时回收整棵进程树；只杀主进程会留下孙进程。
vm 模块或权限模型（--permission）当作运行不可信代码的沙箱.only 提交进主干，不用 || true、跳过测试或删断言的方式让 CI 变绿.only（如 @vitest/eslint-plugin 的 no-focused-tests）；CI 配置检查测试命令没有 || true；新增 .skip 要求写原因和任务编号sql.raw、$queryRawUnsafe 等原始接口，评审确认没有外部输入new Pool、new Client 的位置；压测时观察数据库连接数git diff --exit-code 检查console.log 打业务日志console（如 Biome 的 noConsole），CLI 和脚本可放开；测试里检查日志不含令牌等字段TypeScript 7 下，typescript-eslint 的类型规则、ts-morph 等依赖编译器接口的工具，暂时要配合 TypeScript 6 的接口包使用，类型检查本身用 TypeScript 7 的 tsc。
没有符合条件的规则。
| 类别 | 默认 | 备选（何时用） | 不推荐 |
|---|---|---|---|
| 运行时 | Node.js 仍在维护期的 LTS 主线 | Bun（想要一体化工具或更快启动，并已在目标平台验证原生扩展、信号和子进程行为） Deno（需要默认权限隔离的脚本或边缘运行环境，并已验证所用 npm 包的兼容性） | 已停止维护的版本、奇数号短期版本、预发布版本：没有安全修复或支持期太短 |
| Node 版本管理 | mise（读取项目里声明的版本） | fnm 或 nvm（团队已经在用，且只需管 Node 一种运行时） | 只在 README 里写版本：没法被工具读取和校验 |
| 包管理器 | pnpm（含 workspace） · MIT（待核实） | npm（单包项目，不想多装一个工具） Bun 的包管理器（运行时也用 Bun） | 一个仓库里混用多种包管理器和锁文件：依赖解析结果不一致 |
| 单仓任务编排 | pnpm workspace 自带的过滤和递归命令 | Turborepo 或 Nx（包多、构建慢，需要任务图和缓存） | 包很少时就上任务图和远端缓存：增加配置和运维成本，远端缓存在断网环境也用不了 |
| 类型检查 | TypeScript 7 的 tsc --noEmit · Apache-2.0（待核实） | TypeScript 6 的接口包（typescript-eslint 类型规则、ts-morph 等工具需要编译器编程接口时，与 TypeScript 7 并存） | 把 esbuild、tsx、Node 能运行当成类型通过：它们都不检查类型 依赖编译器插件或 transformer 的方案：TypeScript 7 不支持 |
| 开发时直接运行 .ts | Node 原生的类型擦除 | tsx（代码里还有 enum、参数属性等不可擦除的语法，或需要 tsconfig 的 paths） | 用运行成功代替类型检查：见 TS-011 |
| 构建 | 服务和 CLI 直接用 tsc 输出 JavaScript，不打包 | tsdown（发布库，需要生成声明文件、多入口和 exports 映射）esbuild（需要单文件产物或冷启动敏感） | 发布未编译的 .ts 源码：Node 不处理 node_modules 里的 .ts 文件，消费方用不了 |
| 格式化与 lint | Biome（一个工具同时管格式化和 lint） · MIT（待核实） | ESLint + typescript-eslint + Prettier（需要 Biome 没有的插件生态（如框架专用规则），或存量项目已稳定使用） Oxlint（存量 ESLint 项目想先提速 lint，格式化另选一个工具） | 同时开两个以上格式化工具：互相改对方的输出 |
| 类型感知 lint 的补充 | typescript-eslint 的类型规则（如 no-floating-promises、no-misused-promises、no-unsafe-*），只启用 Biome 覆盖不全的那部分 · MIT（待核实）默认用 Biome，又需要完整的类型感知检查时 | — | — |
| 单元测试 | Vitest · MIT（待核实） | node:test（零依赖的小库或 CLI） Jest（存量项目已在用） | 一个仓库同时维护两套单元测试框架：断言、模拟、配置各一套 |
| 属性测试 | fast-check · MIT（待核实） | — | — |
| 变异测试 | StrykerJS · Apache-2.0（待核实） 核心逻辑需要检验测试是否真的能发现错误时，按模块定期跑，不进每次提交的门禁 | — | — |
| HTTP 模拟 | MSW（在网络层拦截请求） · MIT（待核实） | — | 到处手写 fetch 的替身：和真实请求的行为差别大，维护成本高 |
| 运行时校验 | Zod · MIT（待核实） | Valibot（前端或边缘环境对包体积敏感） 框架自带的 JSON Schema 校验（Fastify / Ajv）（服务端已用 Fastify，校验和 OpenAPI 文档共用一份 schema） | req.body as T 或手写字段检查：运行时没有任何保证 |
| 服务端 HTTP 框架 | Fastify · MIT（待核实） | Hono（需要在 Node、Bun、Deno、边缘环境之间通用，或服务很小） NestJS（团队大、模块多，明确需要依赖注入和统一的组织方式） Express（存量项目） | 用 Node 自带的 http 模块手写路由和中间件：请求体限制、超时、解析边界都要自己补，容易出错 |
| 查询构建器 / ORM | Kysely（类型安全的 SQL 查询构建器）+ node-postgres · Kysely MIT（待核实）；Drizzle ORM Apache-2.0；Prisma ORM Apache-2.0 | Drizzle ORM（希望 schema 写在 TypeScript 里并由它生成迁移） Prisma ORM（团队已熟悉，需要它的关系查询和工具链；断网环境要先验证代码生成步骤不需联网） | 手写字符串拼 SQL：注入风险，见 TS-030 |
| 数据库迁移工具 | 跟随查询层：Kysely 自带迁移器、Drizzle Kit、Prisma Migrate | node-pg-migrate（只用 PostgreSQL，查询层不带迁移） dbmate 等与语言无关的工具（多种语言的服务共用一个数据库时，统一用一个工具（见 17）） | 一个数据库由两套迁移工具同时管理：迁移历史分裂，无法判断当前结构 |
| PostgreSQL 驱动 | node-postgres（pg）+ 连接池 | postgres.js（偏好模板字符串写 SQL，且不用依赖 pg 的查询层） | — |
| OpenAPI 的 TypeScript 生成器 | openapi-typescript（生成类型）+ openapi-fetch（轻量客户端） · MIT（待核实） | Orval（前端需要直接生成 TanStack Query 的 hooks） Hey API（需要生成完整的 SDK（仍是 0.x，升级注意破坏性变化）） | 多个生成器同时产出同一份客户端：两份代码会不一致 手写一份接口类型在前后端之间复制：改接口后必然漂移 |
| 日志 | Pino · MIT（待核实） | Winston（存量项目） | — |
| 并发控制 | p-limit · MIT（待核实） | p-queue（还需要优先级、暂停或速率限制） | — |
tsc --noEmit · Apache-2.0（待核实）paths）tsc 输出 JavaScript，不打包exports 映射）；esbuild（需要单文件产物或冷启动敏感）no-floating-promises、no-misused-promises、no-unsafe-*），只启用 Biome 覆盖不全的那部分 · MIT（待核实）req.body as T 或手写字段检查tsc --noEmitJSON.parse(body) as Userstrict: truepaths 别名，构建后运行时报找不到模块imports 子路径导入npx 某工具@latestPromise.all(rows.map(fetchSomething))exec(\git clone ${url}`)`execFile('git', ['clone', url])vm 模块运行用户提交的代码new Pool()下面的内容还没核实或待补调研，不要当成规则执行。
noFloatingPromises 是否已移出试验分组--experimental-transform-types（只在夜间版文档里看到），未核实正式版minimumReleaseAge 在默认值和显式设置时的严格程度差异（宽松模式会自动放行）需再核对