TypeScript 项目需要严格类型配置…

适用于 TypeScript 新项目、既有项目、API/库开发中需要类型安全、运行时校验、现代语言特性和质量防劣化的场景。

适用场景

解决思路

1. 新项目：使用 2025 tsconfig 基线，启用 `strict` 和 `noUncheckedIndexedAccess`，并选择 Zod 做运行时校验。
2. 既有项目：先将 `strict` 设为 `false` 作为过渡，逐步修复 `any` 为 `unknown`，再添加 `noUncheckedIndexedAccess`。
3. API 开发：在边界使用 Zod schema，用 `z.infer<typeof Schema>` 推导类型，用 `satisfies` 校验路由。
4. 库开发：启用 `declaration: true`，使用 `const` 类型参数，并参考 `advanced-patterns-2025.md`。
5. 使用 2025 `tsconfig.json` 基线：设置 `target` 为 `ES2022`、`module` 为 `NodeNext`、`moduleResolution` 为 `NodeNext`。
6. 在 2025 `tsconfig.json` 基线中设置 `strict` 为 `true`、`noUncheckedIndexedAccess` 为 `true`、`exactOptionalPropertyTypes` 为 `true`。
7. 在 2025 `tsconfig.json` 基线中设置 `verbatimModuleSyntax` 为 `true`、`isolatedModules` 为 `true`、`skipLibCheck` 为 `true`。
8. 在 2025 `tsconfig.json` 基线中设置 `declaration` 为 `true`、`declarationMap` 为 `true`。
9. 为安全始终启用 `noUncheckedIndexedAccess`，强制对数组/对象索引访问做空值检查。
10. 对含可选字段的 API 启用 `exactOptionalPropertyTypes`，区分 `undefined` 与缺失属性。
11. 在 ESM 项目中启用 `verbatimModuleSyntax`，强制显式使用 type-only import。
12. 在类型剥离环境（如 Node.js 22+ 原生 TS 支持）中启用 `erasableSyntaxOnly`。
13. 按仓库类型选择本地 tsconfig 基线（如 CommonJS CLI、NodeNext strict、Next.js bundler），参考 `references/configuration.md`。
14. 使用 `const` 类型参数保留泛型函数中的字面量类型，例如 `createConfig<const T extends Record<string, unknown>>(config: T): T`。
15. 使用 `satisfies` 运算符在保留字面量推断的同时按类型校验对象，例如 `routes satisfies Routes`。
16. 使用模板字面量类型做类型安全的字符串操作与路由参数提取，例如 `ExtractParams<"/users/:id/posts/:postId">` 得到 `"id" | "postId"`。
17. 使用可辨识联合表达结果与动作，并做穷尽性检查：在 `default` 分支声明 `const _exhaustive: never = action` 后抛错。
18. 对外部数据（API、表单、配置文件）使用运行时校验库，因为 TypeScript 类型在运行时消失。
19. 按场景选择校验库：Zod（约 13.5kB，基线速度）适合全栈/tRPC；TypeBox（约 8kB，约 10x 更快）适合 OpenAPI/性能关键；Valibot（约 1.4kB，约 2x 更快）适合 Edge/最小包体。
20. 用 Zod 基础模式定义 schema：`z.object({ id: z.string().uuid(), email: z.string().email(), role: z.enum(['admin', 'user', 'guest']) })`。
21. 用 `z.infer<typeof UserSchema>` 从 Zod schema 推导 `User` 类型。
22. 用 `UserSchema.parse(input)` 在 `parseUser(input: unknown): User` 中校验外部数据。
23. 实现完整 Zod、TypeBox、Valibot 模式时参考 `runtime-validation.md`。
24. 选择 `type` 还是 `interface`：公共 API/库类型用 `interface`；联合类型/映射类型用 `type`；简单对象形状默认用 `interface`。
25. 选择泛型还是联合类型：输出类型依赖输入类型时用泛型；固定已知类型集合用联合类型；构建可复用数据结构时用泛型。
26. 处理未知数据：外部数据（API、用户输入）用 `unknown`；快速原型/迁移可临时用 `any`。
27. 选择运行时校验库：全栈 TypeScript + tRPC 用 Zod；OpenAPI/高性能用 TypeBox；Edge/最小包体用 Valibot。
28. 做全面决策时参考 `decision-trees.md` 的决策框架。
29. 遇到「Property does not exist on type」：定义正确 interface 或使用可选属性。
30. 遇到「Type is not assignable」：修正属性类型或使用运行时校验（Zod）。
31. 遇到「Object is possibly 'undefined'」：使用可选链 `?.` 或类型守卫。
32. 遇到「Cannot find module」：检查文件扩展名（ESM 用 `.js`）和模块解析配置。
33. 遇到编译慢：启用 `incremental`，使用 `skipLibCheck`，考虑 esbuild/swc。
34. 详细错误修复参考 `troubleshooting.md`。
35. 需要复杂类型工具/泛型库时加载 `advanced-types.md`。
36. 设置新项目或优化构建时加载 `configuration.md`。
37. 实现 API 校验或表单处理时加载 `runtime-validation.md`。
38. 使用现代语言特性时加载 `advanced-patterns-2025.md`。
39. 做 TypeScript 设计决策时加载 `decision-trees.md`。
40. 调试 TypeScript 问题时加载 `troubleshooting.md`。
41. 避免宽松相等 `==`/`!=`，使用 `===`/`!==`；仅当注释为「null or undefined」时接受 `== null`。
42. 避免动态代码执行（`eval`、`new Function(str)`、字符串 `setTimeout`），改用直接语法以降低注入风险。
43. 避免修改内置原型（`Object`/`Array`/`Function.prototype`），应扩展或使用自由函数，防止污染 `for…in` 并破坏运行时。
44. 避免变量遮蔽、用 `var` 而非 `let`/`const`、在声明前使用函数，以减少可读性和错误变量问题。
45. 避免在 `switch` 的 `case` 标签中使用逻辑 OR（`case 1 || 2:` 只匹配 1），改用堆叠的 `case` 标签。
46. 避免重复访问深层成员，将解析后的链路缓存到局部变量，尤其是 DOM 操作。
47. 避免未包裹的 IIFE、反斜杠多行字符串、`new Array()`，改用包裹的 IIFE、模板字符串和数组字面量。
48. 查看 `js-quality-antipatterns.md` 获取每个缺陷的合规/不合规示例、严重级别、误报过滤和等价 ESLint/SonarSource 规则。
49. 遇到红旗时停下来重新考虑：外部数据用 `any` 而非 `unknown`。
50. 遇到红旗时停下来重新考虑：使用 `as` 强转但没有运行时校验。
51. 遇到红旗时停下来重新考虑：为方便而禁用严格模式。
52. 遇到红旗时停下来重新考虑：使用 `@ts-ignore` 但没有明确理由。
53. 遇到红旗时停下来重新考虑：索引访问未启用 `noUncheckedIndexedAccess`。
54. 与 `nextjs-core` 集成：为 Server Actions 和 route handlers 提供类型安全。
55. 与 `nextjs-v16` 集成：异步 API 模式和 Cache Components 类型。
56. 与 `mcp-builder` 集成：用 Zod schemas 定义 MCP 工具输入。
57. 相关技能增强：`react`（组件类型、hooks、泛型）、`nextjs`（Server Components、Server Actions 类型）、`drizzle`（类型安全数据库查询）、`prisma`（数据库 schema 的生成 TypeScript 类型）。

适用边界 · 注意事项

• 非 TypeScript 项目，或无法修改 tsconfig/编译配置时，这些编译期与配置类做法不适用。
• 一次性脚本、快速原型或迁移阶段，如果明确可临时接受 any，不必立即引入完整严格模式和运行时校验。
• 运行时环境不支持现代 TS 特性（如 using、decorators、erasableSyntaxOnly），或无法使用 Zod/TypeBox/Valibot 等开源校验库时，相关做法不适用。