TypeScript 编译选项：tsconfig.json 详细配置

TypeScript 项目通过 tsconfig.json 文件来定义编译行为。该文件决定了编译器如何将 .ts 文件转换为 .js 文件，以及严格模式的开启程度。

1. 生成与基础结构

创建 配置文件最简单的方式是使用 TypeScript 自带的命令行工具。

1. 打开 终端或命令行工具。
2. 输入 以下命令并执行：

   tsc --init

3. 查看 项目根目录下生成的 tsconfig.json 文件。

该文件的标准结构包含几个核心字段。compilerOptions 是最关键的部分，用于控制编译行为。

2. 核心编译选项配置

compilerOptions 内部包含大量属性，需根据项目需求逐一设置。

2.1 目标环境与模块系统

设置 代码生成的目标版本和模块系统。

1. 定位 compilerOptions 对象。
2. 修改 target 属性。若代码需在旧浏览器运行，设置为 "es5"；若在较新环境或 Node.js 中运行，设置为 "es2015" 或更高。
3. 修改 module 属性。若开发 Node.js 后端，设置为 "commonjs"；若开发前端项目（如配合 Webpack），设置为 "es2015" 或 "esnext"。

2.2 输出目录结构

控制 编译后的 .js 文件存放位置。

1. 设置 outDir 属性。输入 "./dist"，将编译结果统一输出到 dist 文件夹。
2. 设置 rootDir 属性。输入 "./src"，指定源代码根目录，确保输出结构保持源码的目录层级。

2.3 严格类型检查

启用 严格模式能大幅减少运行时错误，提升代码质量。

1. 查找 strict 属性。
2. 将其设置为 true。这将自动开启所有严格类型检查选项（如 noImplicitAny, strictNullChecks 等）。
3. 若只需部分严格检查，保持 strict 为 false，并 开启 以下具体选项：
   • noImplicitAny: true（禁止隐式 any 类型）。
   • strictNullChecks: true（强制检查 null 和 undefined）。

2.4 模块解析策略

配置 模块导入的查找方式。

1. 设置 moduleResolution。现代前端项目通常 设为 "node"。

2. 配置 路径别名以简化导入路径。

   • 设置 baseUrl 为 "./"。
   • 在 paths 中 定义 映射关系。

   "baseUrl": "./",
   "paths": {
     "@/*": ["src/*"]
   }

   此配置允许使用 import Foo from '@/components/Foo' 代替长相对路径。

3. 编译流程解析

TypeScript 编译器在执行时遵循固定的解析顺序。理解该流程有助于排查配置错误。

4. 常见场景配置模板

不同开发场景下的配置侧重点不同。以下是两种典型环境的推荐配置。

4.1 React 前端项目

React 项目通常需要 JSX 支持及 ES6+ 语法。

1. 确保 target 为 "es5" 或 "es6"（兼容浏览器）。
2. 设置 jsx 选项为 "react"。
3. 开启 esModuleInterop 以支持 CommonJS 模块默认导入。

{
  "compilerOptions": {
    "target": "es5",
    "module": "esnext",
    "lib": ["dom", "es2015"],
    "jsx": "react",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

4.2 Node.js 后端项目

Node.js 原生支持 CommonJS，且不需要 DOM 类型定义。

1. 安装 @types/node 以获取 Node.js 类型支持：npm install -D @types/node。
2. 设置 target 为 "es2017" 或更高（取决于 Node 版本）。
3. 设置 module 为 "commonjs"。

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

5. 排除与包含规则优先级

当 include 和 exclude 同时存在时，编译器按特定逻辑筛选文件。

1. 优先读取 include 指定的文件范围。
2. 从中剔除 exclude 指定的文件。
3. 注意：exclude 默认包含 ["node_modules", "bower_components", "jspm_packages"]，若手动设置 exclude，需显式添加这些目录，否则可能导致编译缓慢或错误。

按照上述步骤完成配置后，运行 tsc 命令即可生成符合预期的 JavaScript 代码。