typescript-strict

TypeScript 严格模式

采用现代 TypeScript 配置和严格类型检查，最大限度地保障安全性并提升开发体验。本指南聚焦于 2025 年 TypeScript 5.x 的最佳实践。

核心要点

什么是严格模式？

• 类型安全：在编译时发现更多错误
• 更好的 IDE 体验：改进自动补全和重构
• 可维护性：使用显式类型编写自说明代码
• 现代默认配置：符合当前 TypeScript 最佳实践

主要功能

• 严格空值检查
• 严格函数类型
• 禁止隐式 any
• 禁止未检查的索引访问
• 正确的模块解析
• 强制使用现代导入/导出语法

推荐的 tsconfig.json（2025）

最简生产环境配置

{
  "compilerOptions": {
    // Type Checking
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,

    // Modules
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": false,
    "verbatimModuleSyntax": true,

    // Emit
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "outDir": "dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "removeComments": false,
    "noEmit": false,

    // Interop
    "isolatedModules": true,
    "allowJs": false,
    "checkJs": false,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "build"]
}

严格标志说明

strict: true（总开关）

启用所有严格类型检查选项：

{
  "strict": true
  // Equivalent to:
  // "noImplicitAny": true,
  // "strictNullChecks": true,
  // "strictFunctionTypes": true,
  // "strictBindCallApply": true,
  // "strictPropertyInitialization": true,
  // "noImplicitThis": true,
  // "alwaysStrict": true
}

新项目始终启用 strict: true。

其他严格标志（2025 年推荐）

标志	用途
noUncheckedIndexedAccess	索引签名返回 T | undefined，而不是 T
noImplicitOverride	覆盖方法时必须使用 override 关键字
noPropertyAccessFromIndexSignature	索引签名必须使用方括号表示法
noFallthroughCasesInSwitch	防止 switch 语句贯穿执行
exactOptionalPropertyTypes	可选属性不能显式设置为 undefined

noUncheckedIndexedAccess（必备）

// With noUncheckedIndexedAccess
const users: Record<string, User> = {};
const user = users['john'];
// Type: User | undefined (correct - must check before use)

if (user) {
  console.log(user.name); // Type narrowed to User
}

始终启用此标志，以防止运行时错误。

模块解析

选择策略

策略	适用场景	是否需要扩展名
Bundler	Vite、Webpack、Bun 项目	否
NodeNext	Node.js 库和服务	是（.js）

moduleResolution: "Bundler"（Vite/Bun）

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler"
  }
}

• 导入时无需文件扩展名
• 导入 JSON 时无需断言
• 支持 package.json 的 exports 字段

moduleResolution: "NodeNext"（Node.js）

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

• 遵循 package.json 中的 type: "module"
• 必须显式指定 .js 扩展名（即使是 .ts 文件）
• 支持条件导出

verbatimModuleSyntax（2025 年推荐）

防止 TypeScript 重写导入/导出语句。

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

// Error: 'User' is a type and must be imported with 'import type'
import { User } from './types';

// Correct
import type { User } from './types';

// Correct (mixed import)
import { fetchUser, type User } from './api';

取代已弃用的 importsNotUsedAsValues 和 preserveValueImports。

Agentic 优化

场景	命令
检查错误	bunx tsc --noEmit
检查单个文件	bunx tsc --noEmit src/utils.ts
显示配置	bunx tsc --showConfig
检查模块解析	bunx tsc --showConfig | grep moduleResolution

快速参考

推荐标志

标志	值	类别
strict	true	类型检查
noUncheckedIndexedAccess	true	类型检查
noImplicitOverride	true	类型检查
noPropertyAccessFromIndexSignature	true	类型检查
noFallthroughCasesInSwitch	true	类型检查
module	ESNext / NodeNext	模块
moduleResolution	Bundler / NodeNext	模块
verbatimModuleSyntax	true	模块
target	ES2022	输出
lib	添加 "ESNext"（TS 6.0+）以使用 Temporal 类型；参见 typescript-temporal	类型检查
isolatedModules	true	互操作
skipLibCheck	true	互操作

如需详细示例、高级模式和最佳实践，请参阅 REFERENCE.md。

参考资料

• TypeScript 手册：https://www.typescriptlang.org/docs/handbook/intro.html
• TSConfig 参考：https://www.typescriptlang.org/tsconfig
• 严格模式指南：https://www.typescriptlang.org/tsconfig#strict
• 模块解析：https://www.typescriptlang.org/docs/handbook/module-resolution.html
• 最佳实践：https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html