TypeScript学习-第11章：配置文件（tsconfig.json）

上一章咱们用模块把代码拆得明明白白，终于摆脱了"大杂烩"困境。可一执行编译命令 tsc 又懵了：编译后的JS文件跟TS源码混在一起，看得眼花缭乱；明明写的是ES6语法，编译后却变成了老旧的ES3；甚至有些测试文件、配置文件也被一并编译......这时候就需要 tsconfig.json 登场了！它就像TS编译的"专属控制面板"，能自定义编译目标、输出路径、文件范围等所有规则，让编译行为完全按你的想法来。今天咱们就手把手搞定这个"配置神器"，从此告别编译混乱的尴尬。

一、配置文件生成：一行命令搞定初始化

刚开始写TS时，很多人会手动创建 tsconfig.json，结果写错字段、漏写配置，编译时各种玄学报错。其实TS早就给咱们准备了"一键生成"命令，自动创建包含所有核心配置的模板文件，按需修改即可。

bash 复制代码

# 初始化tsconfig.json（需先全局安装TypeScript：npm install -g typescript）
tsc --init

执行命令后，项目根目录会生成一个满是注释的 tsconfig.json 文件，里面包含了TS所有可配置项，注释里详细说明了每个配置的作用，咱们只需把需要的配置项注释解开，修改对应值就行，堪称"懒人福音"。

小提示：如果项目中存在 tsconfig.json，执行 tsc 命令时，TS会自动读取该文件的配置；若想指定其他配置文件，可使用 tsc --project 配置文件路径（简写 tsc -p 路径）。

二、核心配置项：吃透compilerOptions与include/exclude

tsconfig.json 的核心是 compilerOptions（编译选项）和 include/exclude（文件范围控制），前者管"怎么编译"，后者管"编译哪些文件"，二者组合就能覆盖绝大多数项目的需求。

1. compilerOptions：编译行为的"核心控制台"

这是配置文件中最关键的部分，包含数十个配置项，咱们挑最常用、最核心的几个来讲，尤其是必开、必配的选项，帮你避开90%的编译坑。

json 复制代码

{
  "compilerOptions": {
    // 1. 编译目标ES版本（必配）：把TS编译成对应版本的JS
    "target": "ES6", // 可选值：ES3、ES5、ES6/ES2015、ES2020等
    // 类比：把"普通话"（TS）翻译成"方言"（对应ES版本），适配不同运行环境

    // 2. 模块系统（必配）：指定生成的模块类型
    "module": "ESNext", // 可选值：CommonJS、ESNext、UMD等
    // 适配场景：Node.js用CommonJS，现代浏览器/框架用ESNext

    // 3. 输出目录（必配）：编译后的JS文件存放路径
    "outDir": "./dist", // 建议放在dist目录，与源码隔离
    // 避坑：不配置的话，JS文件会和TS文件混在同一目录

    // 4. 源码目录（必配）：指定TS源码所在目录
    "rootDir": "./src", // 源码统一放在src目录，编译时按该目录结构输出到outDir
    // 作用：确保dist目录结构与src一致，避免文件混乱

    // 5. 严格模式（必开！）：开启所有类型安全校验规则
    "strict": true, // 等价于开启strictNullChecks、noImplicitAny等所有严格规则
    // 重要性：这是TS类型安全的核心，不开等于白用TS！

    // 6. ES模块互操作（必开）：兼容CommonJS和ES模块
    "esModuleInterop": true, // 解决import CommonJS模块（如Node.js内置模块）的报错问题
    // 场景：导入jQuery、lodash等CommonJS模块时，无需额外断言
  }
}

补充几个实用配置项，按需添加：

"strictNullChecks": true：单独开启空值校验（strict: true 已包含），禁止把 null/undefined 赋值给非空类型；
"noImplicitAny": true：禁止隐式 any 类型（strict: true 已包含），强制所有变量、参数指定类型；
"sourceMap": true：生成SourceMap文件，方便调试TS源码（开发环境开启，生产环境关闭）；
"resolveJsonModule": true：允许导入 .json 文件，并提供类型提示。

2. include/exclude：精准控制编译文件范围

默认情况下，TS会编译项目根目录下所有 .ts、.tsx 文件，但我们通常需要排除测试文件、配置文件、node_modules等，这时候就靠 include（包含）和 exclude（排除）来控制。

json 复制代码

{
  "compilerOptions": { /* 省略编译选项 */ },
  // 包含的文件：只编译src目录下所有TS文件（**表示所有子目录，*表示所有文件）
  "include": ["./src/**/*"],
  // 排除的文件：不编译node_modules、测试文件、dist目录
  "exclude": [
    "./node_modules",
    "./src/**/*.test.ts", // 排除所有.test.ts测试文件
    "./dist"
  ]
}

避坑提醒：exclude 仅对 include 包含的文件生效，若文件不在 include 范围内，即使不排除也不会被编译；node_modules目录默认会被排除，无需手动添加。

三、编译模式：增量编译与监视模式

日常开发中，频繁手动执行 tsc 编译效率很低，TS提供了两种高效编译模式，大幅提升开发体验。

1. 监视模式（开发必备）

用 tsc --watch（简写 tsc -w）开启监视模式，TS会实时监听src目录下的TS文件变化，一旦文件保存，自动触发编译，无需手动执行命令。

bash 复制代码

# 开启监视模式，实时编译文件
tsc --watch

开启后，终端会显示编译状态，文件修改后会自动重新编译，报错信息也会实时更新，开发时全程开启即可。

2. 增量编译（大型项目优化）

大型项目中，TS文件数量多，每次全量编译耗时久，增量编译能只编译修改过的文件，大幅缩短编译时间。只需在 compilerOptions 中添加 "incremental": true 即可。

json 复制代码

{
  "compilerOptions": {
    "incremental": true, // 开启增量编译
    "tsBuildInfoFile": "./dist/.tsbuildinfo" // 存储编译信息的文件，下次编译时读取
  }
}

原理：首次编译时，TS会生成 .tsbuildinfo 文件，记录每个文件的编译状态；后续编译时，仅对比文件变化，只重新编译修改过的文件及依赖它的文件，适合文件数量超过100个的大型项目。

四、实战：按项目类型配置tsconfig.json

不同项目（React/Vue/Node.js）的配置需求不同，下面给出三种常见项目的实战配置，直接复制修改即可使用。

1. React项目配置（TSX语法）

json 复制代码

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "jsx": "react-jsx", // 支持React JSX语法（React 17+无需导入React）
    "moduleResolution": "NodeNext", // 适配现代Node.js模块解析
    "sourceMap": true,
    "resolveJsonModule": true,
    "lib": ["ES2020", "DOM"] // 引入ES2020语法和DOM API类型
  },
  "include": ["./src/**/*"],
  "exclude": ["./node_modules", "./src/**/*.test.tsx"]
}

2. Vue项目配置（Vite+TS）

Vite项目默认会生成基础TS配置，补充核心选项即可：

json 复制代码

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "jsx": "preserve", // Vue JSX语法支持
    "moduleResolution": "NodeNext",
    "sourceMap": true,
    "resolveJsonModule": true,
    "lib": ["ES2020", "DOM"],
    "types": ["vite/client", "vue"] // 引入Vite和Vue的类型声明
  },
  "include": ["./src/**/*", "*.vue"],
  "exclude": ["./node_modules"]
}

3. Node.js项目配置（CommonJS模块）

json 复制代码

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS", // Node.js默认支持CommonJS模块
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    "lib": ["ES2020"] // Node.js项目无需DOM库
  },
  "include": ["./src/**/*"],
  "exclude": ["./node_modules", "./src/**/*.test.ts"]
}

五、避坑指南与深度总结

strict模式必开不犹豫：很多人嫌严格模式麻烦，关闭后TS变成"弱类型检查"，各种空值、隐式any问题会隐藏到运行时，得不偿失。
outDir与rootDir配套使用：单独配置其中一个会导致文件路径混乱，配套配置能确保编译后目录结构与源码一致。
esModuleInterop别漏开：导入CommonJS模块时出现"类型不匹配"报错，大概率是没开这个配置，开启后即可解决。
不同环境配置区分开：开发环境开启sourceMap、watch模式，生产环境关闭sourceMap、开启增量编译，可创建多个配置文件（如tsconfig.dev.json、tsconfig.prod.json）分别对应。
配置报错先查字段拼写：TS对配置字段拼写敏感，比如把"outDir"写成"outdir"会导致配置失效，报错时先检查字段名。

最后总结：tsconfig.json 不是"玄学配置"，而是TS编译的"规则手册"------核心是通过 compilerOptions 定制编译行为，用 include/exclude 控制文件范围，搭配监视模式、增量编译提升开发效率。不同项目的配置虽有差异，但"strict: true""esModuleInterop: true"等核心选项是通用的，掌握这些，就能根据项目需求灵活配置，让TS编译完全按你的预期执行。