tsconfig-options

了解你使用的 TypeScript 选项

概述

TypeScript 的行为在很大程度上取决于配置。

同一段代码可能会因 noImplicitAny 和 strictNullChecks 等选项而通过或无法通过类型检查。了解你的选项，才能有效地使用 TypeScript。

何时使用此技能

• 设置新的 TypeScript 项目
• 代码表现与预期不同
• 调试其他人没有遇到的类型错误
• 决定严格程度

铁律

ALWAYS use a tsconfig.json and enable strict mode for new projects.

关键设置：

• noImplicitAny：当 TypeScript 无法推断类型时，要求显式指定类型
• strictNullChecks：要求在类型中显式处理 null/undefined
• strict：启用所有严格检查（推荐）

最重要的选项

noImplicitAny

控制 TypeScript 是否允许隐式 any 类型：

// With noImplicitAny: false (OFF) - No error
function add(a, b) {
  return a + b;
}
// a and b are implicitly 'any' - dangerous!

// With noImplicitAny: true (ON) - Error
function add(a, b) {
  //         ~  Parameter 'a' implicitly has an 'any' type
  //            ~  Parameter 'b' implicitly has an 'any' type
  return a + b;
}

// Fixed:
function add(a: number, b: number) {
  return a + b;
}

strictNullChecks

控制 null/undefined 是否可用于所有类型：

// With strictNullChecks: false (OFF)
const x: number = null;  // OK, but dangerous

// With strictNullChecks: true (ON)
const x: number = null;
//    ~ Type 'null' is not assignable to type 'number'

// Fixed - be explicit:
const x: number | null = null;  // OK

处理可空值

// strictNullChecks forces you to handle null:
const statusEl = document.getElementById('status');

statusEl.textContent = 'Ready';
// ~~~~~~ 'statusEl' is possibly 'null'.

// Option 1: Check for null
if (statusEl) {
  statusEl.textContent = 'Ready';  // OK
}

// Option 2: Assert non-null (use carefully!)
statusEl!.textContent = 'Ready';  // OK

推荐配置

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,  // Enables all strict checks
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

使用以下命令创建：tsc --init

严格模式包含

strict 标志会启用：

• noImplicitAny
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• strictPropertyInitialization
• noImplicitThis
• alwaysStrict

比严格模式更严格

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true  // Extra safety for array/object access
  }
}

使用 noUncheckedIndexedAccess：

const arr = ['a', 'b', 'c'];
arr[0].toUpperCase();  // Error: Object is possibly 'undefined'

// Must check:
const first = arr[0];
if (first) {
  first.toUpperCase();  // OK
}

迁移路径

对于现有的 JavaScript 项目：

1. 从最基本的设置开始
2. 启用 noImplicitAny
3. 修复所有隐式 any 错误
4. 启用 strictNullChecks
5. 最终启用完整的 strict 模式

抗压指南

1. “严格模式太难了”

压力：“严格模式下错误太多了”

**回应：**每个错误都可能是一个 Bug。逐步修复。

**行动：**启用 strict，每次修复一个文件中的错误。

2. “我们不需要为所有内容指定类型”

压力：“隐式 any 没问题，我们知道类型是什么”

**回应：**你知道，但 TypeScript 不知道。未来的维护者也不会知道。

**行动：**启用 noImplicitAny——类型就是文档。

危险信号——停止并重新考虑

• 项目中没有 tsconfig.json
• 使用命令行标志而不是配置文件
• 没有迁移计划却设置 strict: false
• 团队成员使用不同的设置

快速参考

选项	效果	建议
strict	启用所有严格检查	新项目始终启用
noImplicitAny	要求显式指定类型	必不可少
strictNullChecks	必须显式处理 null/undefined	必不可少
noUncheckedIndexedAccess	数组访问的结果可能是 undefined	考虑启用

归根结底

了解你的选项。启用严格模式。

TypeScript 的行为取决于配置。使用 tsconfig.json，为新项目启用严格模式，并了解 noImplicitAny 和 strictNullChecks 的作用。团队使用一致的配置至关重要。

参考资料

基于 Dan Vanderkam 所著的《Effective TypeScript》第 2 条：了解你使用的 TypeScript 选项。