TypeScript 严格模式与类型安全最佳实践

## 背景与价值

在复杂前端/全栈项目中，类型系统是“防线”。开启严格模式并配合关键编译参数，可显著降低运行期错误、提升重构信心，同时保持构建可控。本文围绕严格模式与高价值参数给出经过验证的解释与示例，兼顾可落地性。

## 核心结论（可直接落地）

• 将 `"strict": true` 作为团队默认；其包含 `noImplicitAny`、`strictNullChecks` 等一组安全增强。
• 在数据密集场景开启 `noUncheckedIndexedAccess` 与 `exactOptionalPropertyTypes`，使下标访问与可选属性的语义更精确。
• 使用 `noImplicitOverride` 防止“无意覆盖”父类方法；配合 `override` 关键字增强可读性。
• 现代工程建议 `moduleResolution: "bundler"`（结合 Vite/Webpack/Rspack 等），与 ESM 生态更一致。
• 构建层面通过 `incremental: true`、项目引用 `composite: true` 加速与稳态化；谨慎使用 `skipLibCheck`。

## tsconfig 关键参数与验证示例

### 严格模式组

• `strict: true`
• 启用一组严格检查（含 `noImplicitAny`、`strictNullChecks` 等）。
• 价值：在类型缺失/空值路径上尽早告警。

• `noImplicitAny: true`
• 未显式类型的变量/参数不可默认为 `any`。
• 示例：

    // 报错：Parameter 'x' implicitly has an 'any' type.
    function f(x) { return x + 1 }

• `strictNullChecks: true`
• `null`/`undefined` 不再可赋给所有类型；必须显式处理。
• 示例：

    const s: string = Math.random() > 0.5 ? "a" : undefined; // 报错
    const t: string | undefined = Math.random() > 0.5 ? "a" : undefined; // 正确

### 精细语义增强

• `noUncheckedIndexedAccess: true`
• 下标访问结果自动带上 `| undefined`，促使显式存在性检查。
• 示例：

    const map: Record<string, number> = { a: 1 };
    const v = map["b"]; // 类型为 number | undefined
    if (v !== undefined) {
      console.log(v.toFixed(2));
    }

• `exactOptionalPropertyTypes: true`
• 可选属性与 `| undefined` 行为区分更严格，读写语义更贴近真实。
• 示例：

    interface User { name?: string }
    const u: User = {};
    // 某些场景下，给可选属性赋值与删除/缺省将产生更精确的类型约束

• `noImplicitOverride: true`
• 覆盖父类方法时必须显式写 `override`；避免误写同名新方法。
• 示例：

    class Base { greet() { console.log("hi") } }
    class Sub extends Base {
      override greet() { console.log("hello") }
    }

• `noPropertyAccessFromIndexSignature: true`
• 具有索引签名的类型不允许“点属性”直接访问，需更显式的索引方式。
• 示例：

    interface Dict { [key: string]: string }
    const d: Dict = { a: "1" };
    // d.a 将被提示不安全；应使用 d["a"]

### 模块与目标

• `moduleResolution: "bundler"`
• 针对现代打包器的解析策略（TS ≥ 5），在 ESM/TS 生态下更一致。

• `target: "ES2020" | "ES2022" | "ES2020+"`
• 选择与运行环境/打包链路匹配的输出目标；更高目标带来更现代的语义（如 `useDefineForClassFields`）。

• `useDefineForClassFields: true`
• 类字段按照标准 `define` 语义发射；与现代 JS 语义一致。

### 构建与工程

• `incremental: true`
• 生成 `.tsbuildinfo`，加速二次编译；适合中大型项目。

• `composite: true`（配合项目引用）
• 使子项目可被其他项目引用与增量构建；强化边界与产物。

• `skipLibCheck: true`（谨慎）
• 跳过 `node_modules` 类型检查可提速，但可能掩盖库类型问题；在 CI/发布前建议开启完整检查或最少在关键包上保守处理。

## 推荐 tsconfig（可复制）

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,

    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "useDefineForClassFields": true,

    "incremental": true,
    "declaration": true,
    "composite": true,
    "sourceMap": true
  },
  "include": ["src"]
}

## 真实场景最佳实践

• 数据层（API/表单）：与 `zod`/`valibot` 等运行时校验结合，类型与运行时一致；即使不引库，也至少在解析点做窄化检查。
• 边界定义：公共 API（函数、组件 props、模块导出）一律显式类型；内部实现允许类型推断但保留严格检查。
• 迭代策略：从 `strictNullChecks` 与 `noImplicitAny` 开始，逐步引入更精细参数（`noUncheckedIndexedAccess` 等）。
• CI 与编辑器：在 CI 使用 `tsc --noEmit` 做纯类型检查；本地编辑器启用 TS Server 的“严格建议”。

## 常见陷阱与应对

• 误用 `any`：可通过 `eslint` 规则（如 `@typescript-eslint/no-explicit-any`）与代码评审收敛。
• `skipLibCheck` 长期开启：短期提速，但发布前或核心模块建议完整类型检查。
• `moduleResolution` 不匹配：在 Node + ESM 混合时，优先统一到打包器友好的策略，并保证路径与扩展名一致性（如 `.js` 映射）。

## 总结

严格模式与精细化编译参数是 TypeScript 的“安全基准线”。当我们以工程化思维启用并坚持这些约束，配合真实可验证的示例与构建策略，代码的可靠性、可维护性与团队协作效率都会显著提升。