TypeScript：8、tsconfig 深入配置

tsconfig 深入配置

tsconfig.json 是 TypeScript 项目的配置文件。它可以统一规定源文件范围、编译目标、模块系统、输出目录以及类型检查规则。

一、配置文件的作用

如果只编译一个文件，可以直接执行：

npx tsc src/index.ts

但在实际项目中，通常包含很多 TypeScript 文件。把配置集中到 tsconfig.json 后，只需要执行：

npx tsc

编译器会按照配置文件自动查找和编译项目文件。

二、基础配置示例

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "CommonJS",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

这个配置表示：

• 从 src 目录读取 TypeScript 文件。
• 把代码编译为 ES2015 目标代码。
• 使用 CommonJS 模块系统。
• 把编译结果输出到 dist。
• 开启严格类型检查。
• 生成 Source Map 文件。

三、控制编译文件范围

1. include

include 用于指定需要编译的文件或目录：

{
  "include": [
    "src/**/*.ts",
    "tests/**/*.ts"
  ]
}

** 可以匹配多级目录，*.ts 可以匹配指定目录下的 TypeScript 文件。

2. exclude

exclude 用于排除不需要编译的文件：

{
  "exclude": [
    "node_modules",
    "dist",
    "src/demo"
  ]
}

常见排除目录包括依赖目录、构建产物目录和临时示例目录。

3. files

files 用于精确指定编译文件：

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

文件数量较少且需要严格控制入口时，可以使用 files。文件较多时，通常使用 include 更方便。

4. extends

extends 可以继承其他配置文件：

{
  "extends": "./configs/base.json",
  "compilerOptions": {
    "outDir": "dist"
  }
}

这种方式适合在多个项目之间共享基础配置，再为每个项目补充差异配置。

四、常用项目选项

1. target

target 用于指定编译后的 JavaScript 目标版本：

{
  "compilerOptions": {
    "target": "ES2015"
  }
}

目标版本越低，编译器通常需要转换更多新语法；目标版本越高，生成代码可能更接近源代码，但对运行环境要求也更高。

2. lib

lib 用于指定代码运行时可用的标准库或宿主环境类型：

{
  "compilerOptions": {
    "target": "ES2015",
    "lib": ["ES2015", "DOM"]
  }
}

DOM 用于浏览器相关类型，ES2015 用于对应 ECMAScript 标准库类型。

3. module

module 用于指定编译后的模块系统：

{
  "compilerOptions": {
    "module": "CommonJS"
  }
}

常见选项包括 CommonJS、AMD、UMD、ES2015 和 ESNext。模块配置要和项目运行环境、打包工具保持一致。

五、控制输入和输出目录

1. rootDir

rootDir 用于指定源代码根目录：

{
  "compilerOptions": {
    "rootDir": "./src"
  }
}

2. outDir

outDir 用于指定编译结果目录：

{
  "compilerOptions": {
    "outDir": "./dist"
  }
}

推荐把源码和编译结果分开，避免生成的 JavaScript 文件污染源代码目录。

3. outFile

outFile 可以把多个文件合并为一个输出文件，但它只适用于特定模块配置和使用场景。现代项目通常更常使用 Webpack 等构建工具完成模块打包。

六、其他常用选项

典型配置：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "removeComments": true,
    "sourceMap": true,
    "noEmitOnError": true
  }
}

七、strict 严格检查

建议在项目中显式开启：

{
  "compilerOptions": {
    "strict": true
  }
}

strict 是一组严格检查选项的集合，常见子选项包括：

• alwaysStrict：始终以严格模式处理模块。
• noImplicitAny：禁止隐式的 any。
• noImplicitThis：禁止类型不明确的 this。
• strictBindCallApply：严格检查 bind、call 和 apply。
• strictFunctionTypes：严格检查函数类型。
• strictNullChecks：严格检查 null 和 undefined。
• strictPropertyInitialization：检查类属性是否初始化。

八、额外检查

{
  "compilerOptions": {
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

这些选项可以帮助发现：

• switch 中遗漏 break 的分支。
• 函数中没有明确返回值的路径。
• 没有使用的局部变量。
• 没有使用的函数参数。

九、配置继承和环境拆分

可以把公共配置放到 configs/base.json：

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "CommonJS",
    "strict": true
  }
}

开发环境配置：

{
  "extends": "./configs/base.json",
  "compilerOptions": {
    "sourceMap": true,
    "noEmitOnError": false
  }
}

生产环境配置：

{
  "extends": "./configs/base.json",
  "compilerOptions": {
    "removeComments": true,
    "noEmitOnError": true
  }
}

十、常用命令

# 使用当前目录的 tsconfig.json
npx tsc

# 指定配置文件
npx tsc --project tsconfig.json

# 只检查，不输出文件
npx tsc --noEmit

# 查看最终生效的配置
npx tsc --showConfig

十一、常见问题

1. No inputs were found

通常是 include 没有匹配到文件。检查当前目录、文件扩展名和匹配路径。

2. rootDir 范围不正确

如果 rootDir 指向 src，但 include 同时包含了 tests，就可能出现目录范围不一致的问题。此时应调整 rootDir 或拆分配置文件。

3. 严格模式导致旧代码报错

严格模式报错通常说明代码中存在隐式类型、空值或初始化问题。建议逐个修复，不要直接把所有类型改成 any。

十二、本章小结

• tsconfig.json 负责统一 TypeScript 编译规则。
• include、exclude、files 控制编译范围。
• target、lib、module 控制运行环境和模块系统。
• rootDir 和 outDir 控制输入输出目录。
• strict 和额外检查选项可以提高代码质量。