TypeScript tsconfig.json 配置详解与模板（基于 TypeScript 5.8.3）

tsconfig.json 是 TypeScript 的配置文件，用于控制编译行为、类型检查和输出选项。本文档详细列出 TypeScript 5.8.3 的所有配置项，解释其功能作用，并提供多个常用模板，可直接用于不同开发场景。

1. tsconfig.json 配置结构

tsconfig.json 通常包含以下顶级字段：

• compilerOptions：定义编译器行为的核心选项。
• include：指定编译的文件或目录。
• exclude：排除不需要编译的文件或目录。
• extends：继承其他配置文件。
• files：指定具体编译文件列表。
• references：支持项目引用（多项目管理）。

以下是所有 compilerOptions 配置项的详细说明，分为几大类。

2. compilerOptions 配置项详解

2.1 基本选项

示例：基本配置

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true
  }
}

2.2 严格类型检查选项

示例：严格模式

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

2.3 模块解析选项

示例：模块解析

{
  "compilerOptions": {
    "moduleResolution": "nodenext",
    "baseUrl": "src",
    "paths": {
      "@utils/*": "utils/*"
    },
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

2.4 额外检查选项

示例：额外检查

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

2.5 实验性选项

示例：装饰器

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

2.6 高级选项

示例：高级选项

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "incremental": true
  }
}

2.7 源文件控制

示例：文件控制

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

3. 常用 tsconfig.json 模板

以下是针对不同场景的推荐配置模板，可直接使用或根据需求调整。

3.1 Node.js 项目模板

适用于 Node.js 项目，支持 ESM 和 CommonJS，推荐严格类型检查。

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "sourceMap": true,
    "incremental": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

适用场景：Node.js 后端开发、CLI 工具，支持最新 ECMAScript 特性。

3.2 React 项目模板

适用于 React 项目，使用 Vite 或 Create React App。

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "jsx": "react-jsx",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node",
    "allowJs": true,
    "baseUrl": "src",
    "paths": {
      "@components/*": ["components/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

适用场景：React Web 应用，使用 JSX 和模块别名。

3.3 TypeScript 库开发模板

适用于开发可发布的 TypeScript 库，生成声明文件。

{
  "compilerOptions": {
    "target": "es2018",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "test"]
}

适用场景：开发 npm 包，生成类型声明文件供其他项目使用。

3.4 Monorepo 项目模板

适用于使用项目引用的多项目管理（如 Monorepo）。

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "composite": true,
    "incremental": true,
    "declaration": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "references": [{ "path": "../shared" }]
}

适用场景：大型项目，包含多个子项目（如前端和后端共享代码）。

3.5 实验性特性模板

适用于使用装饰器或实验性功能的项目。

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

适用场景：使用装饰器的框架（如 Angular）或实验性功能开发。

4. 最佳实践

• 启用严格模式：设置 "strict": true 以确保类型安全。
• 模块系统选择：Node.js 项目使用 "nodenext"，前端项目使用 "esnext"。
• 模块别名：通过 baseUrl 和 paths 简化导入路径。
• 增量编译：启用 incremental 和 composite 提高编译性能。
• 跳过库检查：设置 skipLibCheck: true 加快编译速度。
• 声明文件：库开发时启用 declaration 和 declarationMap。

5. 注意事项

• 配置继承：使用 extends 继承基础配置文件，减少重复。

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

• 环境兼容性：根据目标运行环境选择 target 和 lib。
• 调试支持：启用 sourceMap 以便在浏览器或 Node.js 中调试。

6. 资源与进一步学习

• 官方文档：https://www.typescriptlang.org/tsconfig
• TypeScript Handbook：https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
• GitHub 仓库：https://github.com/microsoft/TypeScript