TypeScript 中文文档

Appearance

tsconfig.json 配置文件 ​

概述 ​

tsconfig.json 是 TypeScript 项目的配置文件，用于指定编译选项、文件包含规则、模块解析策略等。通过配置文件，你可以统一管理项目的 TypeScript 编译设置，确保团队成员使用相同的编译规则。

TypeScript 编译器（tsc）会自动查找项目根目录下的 tsconfig.json 文件，并根据其中的配置进行编译。如果没有找到配置文件，编译器会使用默认配置。

配置文件结构 ​

tsconfig.json 是一个 JSON 文件，包含以下主要部分：

json
{
  "compilerOptions": {
    // 编译选项
  },
  "include": [
    // 包含的文件
  ],
  "exclude": [
    // 排除的文件
  ],
  "extends": "./base.json",
  "files": [
    // 明确指定的文件列表
  ],
  "references": [
    // 项目引用
  ]
}

主要配置项说明 ​

  • compilerOptions：编译选项，控制 TypeScript 编译器的行为
  • include：指定要包含的文件或目录（支持 glob 模式）
  • exclude：指定要排除的文件或目录（支持 glob 模式）
  • extends：继承其他配置文件
  • files：明确指定要编译的文件列表
  • references：项目引用，用于 TypeScript 项目引用功能

基本配置示例 ​

示例 1：最简单的配置 ​

json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["src/**/*"]
}

这个配置：

  • 将 TypeScript 编译为 ES2020 标准的 JavaScript
  • 使用 CommonJS 模块系统
  • 输出目录为 ./dist
  • 源代码目录为 ./src
  • 启用严格模式
  • 包含 src 目录下的所有文件

示例 2：Node.js 项目配置 ​

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

示例 3：前端项目配置（React/Vue） ​

json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

常用编译选项 ​

目标版本和模块系统 ​

json
{
  "compilerOptions": {
    // 编译目标：指定编译后的 JavaScript 版本
    "target": "ES2020",  // 可选值：ES3, ES5, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext
    
    // 模块系统：指定使用的模块系统
    "module": "commonjs",  // 可选值：none, commonjs, amd, system, umd, es6, es2015, es2020, esnext, node16, nodenext
    
    // 库文件：指定包含的类型定义
    "lib": ["ES2020", "DOM"],  // 包含 ES2020 和 DOM 的类型定义
  }
}

输出选项 ​

json
{
  "compilerOptions": {
    // 输出目录：编译后的文件输出位置
    "outDir": "./dist",
    
    // 根目录：源代码的根目录
    "rootDir": "./src",
    
    // 输出文件：是否生成单个输出文件（需要 module 为 amd 或 system）
    "outFile": "./dist/bundle.js",
    
    // 不生成输出文件：只进行类型检查，不生成 JavaScript 文件
    "noEmit": true,
    
    // 删除注释：编译时删除注释
    "removeComments": true,
    
    // 生成声明文件：生成 .d.ts 类型声明文件
    "declaration": true,
    "declarationDir": "./types"
  }
}

类型检查选项 ​

json
{
  "compilerOptions": {
    // 严格模式：启用所有严格类型检查选项
    "strict": true,
    
    // 以下选项在 strict: true 时自动启用，也可以单独配置：
    
    // 不允许隐式 any 类型
    "noImplicitAny": true,
    
    // 不允许 null 和 undefined 赋值给其他类型
    "strictNullChecks": true,
    
    // 严格检查函数参数类型
    "strictFunctionTypes": true,
    
    // 严格检查 bind、call、apply 的参数
    "strictBindCallApply": true,
    
    // 严格检查类属性初始化
    "strictPropertyInitialization": true,
    
    // 禁止 this 隐式 any
    "noImplicitThis": true,
    
    // 总是使用严格模式解析
    "alwaysStrict": true,
    
    // 不允许未使用的局部变量
    "noUnusedLocals": true,
    
    // 不允许未使用的参数
    "noUnusedParameters": true,
    
    // 不允许函数没有返回值
    "noImplicitReturns": true,
    
    // 不允许 fallthrough 的 case 语句
    "noFallthroughCasesInSwitch": true
  }
}

模块解析选项 ​

json
{
  "compilerOptions": {
    // 模块解析策略
    "moduleResolution": "node",  // 可选值：node, classic, bundler, node16, nodenext
    
    // 基础路径：用于解析非相对模块导入
    "baseUrl": "./",
    
    // 路径映射：将模块路径映射到实际路径
    "paths": {
      "@/*": ["src/*"],
      "components/*": ["src/components/*"],
      "utils/*": ["src/utils/*"]
    },
    
    // 类型根目录：查找类型定义的目录
    "typeRoots": ["./node_modules/@types"],
    
    // 类型包：自动包含的类型包
    "types": ["node", "jest"],
    
    // 允许导入 JSON 模块
    "resolveJsonModule": true,
    
    // ES 模块互操作
    "esModuleInterop": true,
    
    // 允许默认导入 CommonJS 模块
    "allowSyntheticDefaultImports": true
  }
}

JSX 选项 ​

json
{
  "compilerOptions": {
    // JSX 编译方式
    "jsx": "react-jsx",  // 可选值：preserve, react, react-native, react-jsx, react-jsxdev
    
    // JSX 工厂函数（jsx: "react" 时使用）
    "jsxFactory": "React.createElement",
    
    // JSX Fragment 工厂函数
    "jsxFragmentFactory": "React.Fragment"
  }
}

其他常用选项 ​

json
{
  "compilerOptions": {
    // 允许 JavaScript 文件
    "allowJs": true,
    
    // 检查 JavaScript 文件
    "checkJs": true,
    
    // 跳过类型检查库文件（加快编译速度）
    "skipLibCheck": true,
    
    // 强制文件名大小写一致
    "forceConsistentCasingInFileNames": true,
    
    // 允许导入 .ts 扩展名
    "allowImportingTsExtensions": true,
    
    // 隔离模块：确保每个文件可以安全地作为独立模块使用
    "isolatedModules": true,
    
    // 增量编译：启用增量编译以提高性能
    "incremental": true,
    
    // 复合项目：启用项目引用功能
    "composite": true,
    
    // 源映射：生成 .map 文件用于调试
    "sourceMap": true,
    
    // 内联源映射
    "inlineSourceMap": true
  }
}

文件包含和排除 ​

include 选项 ​

include 指定要包含在编译中的文件或目录，支持 glob 模式：

json
{
  "include": [
    "src/**/*",           // src 目录下的所有文件
    "tests/**/*.ts",      // tests 目录下的所有 .ts 文件
    "*.ts"                // 根目录下的所有 .ts 文件
  ]
}

exclude 选项 ​

exclude 指定要排除的文件或目录，默认排除 node_modules：

json
{
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts",       // 所有测试文件
    "**/*.spec.ts",       // 所有规范文件
    "build"               // build 目录
  ]
}

提示

如果没有指定 include，TypeScript 会包含当前目录及子目录下的所有 .ts、.tsx、.d.ts 文件（除了 exclude 指定的文件）。

files 选项 ​

files 明确指定要编译的文件列表（较少使用）：

json
{
  "files": [
    "src/index.ts",
    "src/app.ts"
  ]
}

配置文件继承 ​

使用 extends 可以继承其他配置文件，避免重复配置：

基础配置文件（base.json） ​

json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

继承配置文件（tsconfig.json） ​

json
{
  "extends": "./base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

继承的配置会被当前配置覆盖，支持多级继承。

项目引用 ​

项目引用（Project References）允许将大型项目拆分为多个子项目，提高编译性能：

主项目配置（tsconfig.json） ​

json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true
  },
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/utils" },
    { "path": "./packages/api" }
  ]
}

子项目配置（packages/core/tsconfig.json） ​

json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "../../dist/core"
  },
  "references": [
    { "path": "../utils" }
  ]
}

实际应用场景 ​

场景 1：Monorepo 项目配置 ​

json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "@shared/*": ["../shared/src/*"],
      "@utils/*": ["../utils/src/*"]
    },
    "composite": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../shared" },
    { "path": "../utils" }
  ]
}

场景 2：库项目配置 ​

json
{
  "compilerOptions": {
    "target": "ES2018",
    "module": "ESNext",
    "lib": ["ES2018"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

场景 3：测试项目配置 ​

json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "types": ["jest", "node"],
    "noImplicitAny": false
  },
  "include": [
    "src/**/*",
    "tests/**/*"
  ]
}

配置文件查找顺序 ​

TypeScript 编译器按以下顺序查找配置文件：

  1. 命令行指定的 --project 或 -p 选项
  2. 当前目录的 tsconfig.json
  3. 向上查找父目录的 tsconfig.json，直到找到包含 files 或 include 的配置
  4. 如果都没找到，使用默认配置

注意事项 ​

注意

  1. JSON 格式严格：tsconfig.json 必须是有效的 JSON 文件，不支持注释（但某些工具支持带注释的 JSONC 格式）。

  2. 路径解析：baseUrl 和 paths 只影响类型检查，不影响运行时模块解析。运行时需要使用打包工具（如 webpack、rollup）配置相应的路径别名。

  3. 模块系统：module 选项影响编译输出，moduleResolution 影响模块解析方式，两者需要匹配。

  4. 严格模式：建议始终启用 strict: true，可以在开发早期发现潜在问题。

  5. 性能优化：对于大型项目，启用 incremental: true 和 skipLibCheck: true 可以显著提高编译速度。

最佳实践

  1. 使用 extends：创建基础配置文件，各子项目继承基础配置，避免重复。

  2. 明确 include/exclude：明确指定包含和排除的文件，避免意外编译不需要的文件。

  3. 启用严格模式：始终启用 strict: true，提高代码质量。

  4. 合理使用 paths：使用路径映射简化导入路径，但要注意与运行时配置保持一致。

  5. 项目引用：对于大型项目，使用项目引用功能拆分项目，提高编译性能。

  6. 版本控制：将 tsconfig.json 提交到版本控制系统，确保团队使用相同的配置。

  7. 文档化：对于复杂的配置，添加注释说明（如果使用支持注释的工具）或创建配置说明文档。

相关链接 ​

基于 VitePress 构建

Copyright © 2026 TypeScript 中文文档