tsconfig.json 详解

tsconfig.json 是 TypeScript 项目的核心配置文件，它告诉 TypeScript 编译器（tsc）如何编译你的项目。

创建 tsconfig.json

你通常不需要手动创建它。在项目根目录下，使用 TypeScript 编译器提供的命令是最佳实践：

# 使用 tsc（TypeScript 编译器）初始化一个配置文件
npx tsc --init

运行这个命令后，会在当前目录生成一个 tsconfig.json 文件，其中包含了几乎所有可用的配置选项，并且大部分都被注释掉了，还附有详细的说明。

核心结构

一个典型的 tsconfig.json 主要包含以下几个部分：

{
  "compilerOptions": {
    // ... 编译器选项
  },
  "include": [
    // ... 要编译的文件
  ],
  "exclude": [
    // ... 要排除的文件
  ],
  "files": [
    // ... 明确指定的文件列表（不常用）
  ],
  "references": [
    // ... 用于项目引用（Project References）
  ]
}

• compilerOptions：这是最重要的部分，用于配置编译过程中的各种规则和行为。
• include：指定一个文件 glob 模式列表，指明哪些文件需要被编译。例如 ["src/**/*"]。
• exclude：指定一个文件 glob 模式列表，指明哪些文件应该被排除在编译之外。默认会排除 node_modules、bower_components、jspm_packages 等。
• files：明确地列出需要编译的文件列表。如果项目文件很少，可以用这个，但不如 include 灵活。
• references：用于配置项目引用，将一个大型项目拆分成多个相互依赖的小项目。

最重要的编译器选项 (compilerOptions)

这里列举一些最常用和关键的选项：

目标与模块 (Target & Module)

{
  "compilerOptions": {
    "target": "ES2020",        // 编译生成的 JavaScript 版本，如 "ES5", "ES6"/"ES2015", "ES2017", "ESNext"
    "module": "commonjs",      // 使用的模块系统，如 "commonjs" (Node.js), "es2015", "esnext", "amd", "umd"
    "lib": ["ES2020", "DOM"],  // 指定要包含在编译中的库文件定义（如浏览器环境 DOM、ES6+ 新特性等）
  }
}

• target：你的代码要被编译成哪个版本的 JS。如果想在旧版浏览器中运行，就选择 "ES5"；如果是现代浏览器或 Node.js 环境，可以选择更新的版本。
• module：代码使用何种模块规范组织。如果你的后端是 Node.js，常用 "commonjs"；如果是前端打包工具（如 Webpack、Rollup），它们通常支持 "esnext"，然后由打包器自己处理。
• lib：指定项目运行环境提供了哪些“内置”的 API（如 document, Promise, Map, Set）。如果写前端项目，一定要包含 "DOM"。

输出与目录 (Output & Directories)

{
  "compilerOptions": {
    "outDir": "./dist",          // 将编译后的 .js 文件输出到哪个目录
    "rootDir": "./src",          // 指定源文件（.ts）的根目录，控制输出目录的结构
    "removeComments": true,      // 删除编译后文件中的所有注释
    "noEmit": true,              // 不生成输出文件（只做类型检查，通常用于与 Babel 配合或开发时检查）
  }
}

• outDir 和 rootDir 通常配合使用，将 src 下的 TS 文件，按照原有目录结构输出到 dist 目录。

严格模式 (Strictness)

TypeScript 的强大之处在于其严格的类型检查。建议新手从一开始就开启最严格的模式。

{
  "compilerOptions": {
    "strict": true, // 启用所有严格类型检查选项！这是最重要的一个开关，这能帮助你避免大量潜在的运行时错误。

    // 以下选项在 "strict": true 时默认全部为 true，你也可以单独关闭某个
    // "noImplicitAny": true,         // 禁止隐式的 any 类型
    // "strictNullChecks": true,      // 启用严格的 null 和 undefined 检查
    // "strictFunctionTypes": true,   // 对函数类型进行更严格的检查
    // "strictBindCallApply": true,   // 对 bind, call, apply 方法进行更严格的检查
    // "alwaysStrict": true,          // 以严格模式解析并为每个源文件生成 "use strict"
  }
}

其他常用选项

{
  "compilerOptions": {
    "allowJs": true,            // 允许编译 JavaScript 文件
    "checkJs": true,            // 在 .js 文件中报告错误（通常与 allowJs 一起使用）
    "jsx": "react-jsx",         // 在 .tsx 文件中支持 JSX，编译方式为 React 17+ 的新转换方式
    "declaration": true,        // 生成相应的 .d.ts 声明文件（用于发布库）
    "declarationMap": true,     // 为声明文件生成 sourcemap
    "sourceMap": true,          // 生成相应的 .map 文件，用于调试
    "esModuleInterop": true,    // 为了兼容 CommonJS 和 ES Module 的导入，生成辅助函数。**基本永远设为 true**
    "skipLibCheck": true,       // 跳过所有声明文件（.d.ts）的类型检查，加快编译速度
    "forceConsistentCasingInFileNames": true, // 禁止对同一文件使用不一致的大小写引用
    "resolveJsonModule": true   // 允许导入 JSON 模块
  }
}

示例配置

示例 1：一个简单的 Node.js 项目

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

示例 2：一个 React 前端项目 (与 Vite/Webpack 配合)

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext", // 或 "esnext"
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "moduleResolution": "node", // 如何查找模块
    "resolveJsonModule": true,
    "isolatedModules": true, // 确保每个文件都能被安全地转译
    "noEmit": true, // 由打包工具（如 Vite）来处理编译和生成文件，tsc 只负责类型检查
    "jsx": "react-jsx"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

注意：在像 Vite 这样的现代前端工具中，"noEmit": true 很常见，因为它们使用 esbuild 或 swc 进行更快的转译，而 tsc 只用作类型检查器。

如何使用配置进行编译

配置好后，在项目根目录下直接运行 tsc 命令即可。

# 编译整个项目（根据 tsconfig.json）
npx tsc

# 监听文件变化，自动重新编译
npx tsc --watch

# 编译特定项目（如果存在多个 tsconfig.json）
npx tsc -p ./path-to-project/tsconfig.json

# 只进行类型检查，不生成文件（如果设置了 "noEmit": true，则默认行为就是如此）
npx tsc --noEmit