TypeScript 配置文件 tsconfig.json

tsconfig.json 是 TypeScript 项目的配置文件，它定义了 TypeScript 编译器的编译选项和项目的文件结构。本章节将详细介绍 tsconfig.json 的配置选项和使用方法。

tsconfig.json 作用

tsconfig.json 文件的主要作用：

1. 配置编译选项：定义 TypeScript 编译器的行为，如目标 ECMAScript 版本、模块系统、严格模式等
2. 指定文件范围：定义哪些文件需要编译，哪些文件需要排除
3. 统一编译配置：为整个项目提供统一的编译配置，确保所有文件使用相同的编译选项
4. 提升开发体验：IDE 可以根据 tsconfig.json 提供更好的类型提示和错误检查

常用配置项

基本配置

{
  "compilerOptions": {
    "target": "es2015",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

详细配置项说明

target

指定编译目标 ECMAScript 版本。

可选值：

• es3（默认）
• es5
• es6 / es2015
• es2016
• es2017
• es2018
• es2019
• es2020
• es2021
• es2022
• esnext

示例：

"target": "es2015"

module

指定模块系统。

可选值：

• none
• commonjs
• amd
• system
• umd
• es2015 / es6
• es2020
• esnext

示例：

"module": "commonjs"

outDir

指定编译输出目录。

示例：

"outDir": "dist"

rootDir

指定源代码根目录。

示例：

"rootDir": "src"

strict

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

示例：

"strict": true

esModuleInterop

启用 ES 模块互操作性，允许使用 import 语法导入 CommonJS 模块。

示例：

"esModuleInterop": true

lib

指定要包含的库文件。

示例：

"lib": ["es2015", "dom"]

allowJs

允许编译 JavaScript 文件。

示例：

"allowJs": true

checkJs

检查 JavaScript 文件的类型。

示例：

"checkJs": true

sourceMap

生成 source map 文件。

示例：

"sourceMap": true

declaration

生成声明文件（.d.ts）。

示例：

"declaration": true

declarationMap

为声明文件生成 source map。

示例：

"declarationMap": true

noEmit

不生成输出文件。

示例：

"noEmit": true

noEmitOnError

当有错误时不生成输出文件。

示例：

"noEmitOnError": true

removeComments

移除注释。

示例：

"removeComments": true

resolveJsonModule

允许导入 JSON 文件。

示例：

"resolveJsonModule": true

编译排除与包含

include

指定需要编译的文件或目录。

示例：

"include": [
  "src/**/*",
  "tests/**/*"
]

exclude

指定需要排除的文件或目录。

示例：

"exclude": [
  "node_modules",
  "dist",
  "**/*.test.ts"
]

files

指定需要编译的具体文件列表。

示例：

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

自动编译配置

watch 模式

使用 --watch 选项启动自动编译：

tsc --watch

也可以在 package.json 中添加脚本：

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch"
  }
}

然后运行：

npm run watch

tsconfig.json 中的 watch 配置

TypeScript 3.8+ 支持在 tsconfig.json 中配置 watch 选项：

{
  "compilerOptions": {
    // 其他配置...
  },
  "watchOptions": {
    "watchFile": "fixedPollingInterval",
    "watchDirectory": "fixedPollingInterval",
    "fallbackPolling": "dynamicPriority",
    "synchronousWatchDirectory": true,
    "excludeDirectories": ["node_modules", "dist"]
  }
}

实战：配置 TypeScript 项目

示例 1：基本项目配置

{
  "compilerOptions": {
    "target": "es2015",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "sourceMap": true,
    "declaration": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

示例 2：React 项目配置

{
  "compilerOptions": {
    "target": "es2018",
    "module": "esnext",
    "moduleResolution": "node",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  },
  "include": [
    "src"
  ],
  "exclude": [
    "node_modules"
  ]
}

示例 3：Node.js 项目配置

{
  "compilerOptions": {
    "target": "es2018",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "sourceMap": true,
    "declaration": true,
    "resolveJsonModule": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts"
  ]
}

小结

本章节介绍了 TypeScript 配置文件 tsconfig.json 的使用，包括：

• tsconfig.json 的作用
• 常用配置项（target、module、outDir、rootDir、strict、esModuleInterop 等）
• 编译排除与包含（include、exclude、files）
• 自动编译配置（watch 模式）
• 实战：配置 TypeScript 项目

tsconfig.json 是 TypeScript 项目的重要配置文件，通过合理配置 tsconfig.json，你可以控制 TypeScript 编译器的行为，确保项目的类型安全性和编译效率。

在实际开发中，应该根据项目的具体需求选择合适的配置选项，以获得最佳的开发体验和编译效果。