TypeScript 配置文件 `tsconfig.json`

TypeScript 配置文件 tsconfig.json 中 compilerOptions 核心配置项的具体含义和常用配置。

一、compilerOptions 核心概念

compilerOptions 是 tsconfig.json 中最核心的配置区块，用于告诉 TypeScript 编译器（tsc）如何编译你的 TypeScript 代码，比如编译后的代码版本、是否开启严格模式、模块系统、输出目录等。

• 如果省略 compilerOptions，TS 会使用默认值 （可通过 tsc --showConfig 查看默认配置）。
• 配置项均为可选，但实际项目中建议显式配置关键选项，保证编译行为可控。

二、常用核心配置项（按使用频率排序）

1. 严格模式相关（重中之重）

严格模式是 TS 类型安全的核心，推荐项目中开启 strict: true（会自动开启以下所有严格选项），也可按需单独配置：

{
  "compilerOptions": {
    "strict": true, // 开启所有严格模式（推荐）
    "strictNullChecks": true, // 不允许 null/undefined 赋值给非空类型
    "strictPropertyInitialization": true, // 要求类属性必须初始化（你之前问的）
    "strictFunctionTypes": true, // 严格检查函数参数/返回值类型
    "noImplicitAny": true, // 不允许隐式 any 类型（比如未标注类型的变量）
    "noImplicitThis": true, // 不允许 this 隐式指向 any 类型
    "alwaysStrict": true // 编译后的 JS 代码顶部添加 "use strict"
  }
}

2. 目标环境与模块

控制编译后的 JS 版本和模块系统：

{
  "compilerOptions": {
    "target": "ES6", // 编译后的 JS 版本（ES3/ES5/ES6/ES2020/ESNext 等）
    "module": "ES6", // 模块系统（CommonJS/ES6/ESNext/UMD/AMD 等）
    "moduleResolution": "NodeNext", // 模块解析策略（Node/NodeNext/Classic）
    "lib": ["ES6", "DOM"], // 指定编译时要包含的库（比如 DOM 用于浏览器环境）
    "esModuleInterop": true, // 兼容 CommonJS 和 ES 模块（比如 import React from 'react'）
    "skipLibCheck": true // 跳过第三方库（如 node_modules）的类型检查（提升编译速度）
  }
}

3. 输出配置

控制编译后文件的输出路径、格式：

{
  "compilerOptions": {
    "outDir": "./dist", // 编译后的 JS 文件输出目录（推荐）
    "rootDir": "./src", // 源文件（TS）的根目录（避免编译无关文件）
    "declaration": true, // 生成 .d.ts 类型声明文件（库开发必备）
    "sourceMap": true, // 生成 sourceMap 文件（调试时关联 TS 源码）
    "removeComments": false, // 是否移除注释（生产环境可设为 true）
    "noEmitOnError": true // 有编译错误时不生成 JS 文件（避免错误代码上线）
  }
}

4. 代码检查相关（辅助规范）

{
  "compilerOptions": {
    "noUnusedLocals": true, // 检测未使用的变量并报错
    "noUnusedParameters": true, // 检测未使用的函数参数并报错
    "noImplicitReturns": true, // 要求函数所有分支都有返回值
    "noFallthroughCasesInSwitch": true // 禁止 switch 语句的 case 穿透（无 break）
  }
}

三、完整的 tsconfig.json 示例（通用项目模板）

{
  "compilerOptions": {
    /* 基础配置 */
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2020", "DOM"],
    "esModuleInterop": true,
    "skipLibCheck": true,

    /* 严格模式 */
    "strict": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,

    /* 输出配置 */
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "declaration": false, // 业务项目可关闭，库项目开启
    "noEmitOnError": true,

    /* 代码规范 */
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true
  },
  "include": ["./src/**/*"], // 要编译的文件（src 下所有 TS 文件）
  "exclude": ["node_modules", "dist"] // 排除的文件/目录
}

四、如何验证配置是否生效

1. 执行 tsc --showConfig 命令，会打印当前项目实际生效的 TS 配置（包含默认值 + 自定义配置）；
2. 执行 tsc 编译代码，观察是否按预期报错（比如未初始化的类属性）、输出文件是否到 dist 目录。

总结

1. compilerOptions 是 tsconfig.json 的核心，用于控制 TS 编译行为，优先开启 strict: true 保证类型安全；
2. 核心配置分为四类：严格模式、目标 / 模块、输出配置、代码检查，可根据项目类型（业务 / 库）调整；
3. 配置后通过 tsc --showConfig 验证生效状态，避免配置写错导致不生效。