Skip to content

tsconfig 配置详解

· 7 min
TypeScripttsconfig配置编译选项项目配置

tsconfig.json 是 TypeScript 项目的配置文件，定义了编译器的行为和项目结构。

基本结构#

// TypeScript 5.x
{
  "compilerOptions": {
    // 编译器选项
  },
  "include": [
    // 包含的文件
  ],
  "exclude": [
    // 排除的文件
  ],
  "files": [
    // 指定的文件列表
  ],
  "extends": "",
  // 继承的配置
  "references": [
    // 项目引用
  ]
}

文件包含#

include 和 exclude#

{
  "include": [
    "src/**/*", // src 下所有文件
    "tests/**/*", // tests 下所有文件
    "types/**/*.d.ts" // types 下所有声明文件
  ],
  "exclude": [
    "node_modules", // 排除 node_modules
    "dist", // 排除输出目录
    "**/*.spec.ts", // 排除测试文件
    "**/*.test.ts"
  ]
}

files#

指定具体文件（不使用通配符）：

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

编译目标#

target#

指定 ECMAScript 目标版本：

{
  "compilerOptions": {
    // 常用目标
    "target": "ES2015", // ES6
    "target": "ES2020", // 支持可选链、空值合并
    "target": "ES2022", // 支持顶层 await
    "target": "ESNext" // 最新特性
  }
}

lib#

指定要包含的库文件：

{
  "compilerOptions": {
    "lib": [
      "ES2020", // ES2020 标准库
      "DOM", // DOM API
      "DOM.Iterable", // DOM 可迭代
      "WebWorker" // Web Worker API
    ]
  }
}

模块配置#

module#

指定模块系统：

{
  "compilerOptions": {
    // 常用模块系统
    "module": "ESNext", // ES 模块
    "module": "CommonJS", // Node.js CommonJS
    "module": "Node16", // Node.js 16+ ESM/CJS
    "module": "NodeNext" // 最新 Node.js 模块
  }
}

moduleResolution#

指定模块解析策略：

{
  "compilerOptions": {
    "moduleResolution": "node", // Node.js 解析
    "moduleResolution": "node16", // Node.js 16+
    "moduleResolution": "bundler" // 打包工具（Vite, Webpack）
  }
}

baseUrl 和 paths#

配置路径别名：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@types": ["src/types/index.ts"]
    }
  }
}

严格模式#

strict#

启用所有严格类型检查：

{
  "compilerOptions": {
    "strict": true
    // 等同于启用以下所有选项
  }
}

严格选项详解#

{
  "compilerOptions": {
    // 启用严格的空值检查
    "strictNullChecks": true,


    // 函数参数双向协变检查
    "strictFunctionTypes": true,


    // 严格的属性初始化检查
    "strictPropertyInitialization": true,


    // 启用严格的 bind/call/apply 检查
    "strictBindCallApply": true,


    // 隐式 any 报错
    "noImplicitAny": true,


    // 隐式 this 报错
    "noImplicitThis": true,


    // 捕获变量使用前检查
    "useUnknownInCatchVariables": true,


    // 总是严格模式
    "alwaysStrict": true
  }
}

代码质量检查#

{
  "compilerOptions": {
    // 未使用的局部变量报错
    "noUnusedLocals": true,


    // 未使用的参数报错
    "noUnusedParameters": true,


    // 不是所有路径都有返回值时报错
    "noImplicitReturns": true,


    // switch 语句落空检查
    "noFallthroughCasesInSwitch": true,


    // 索引签名访问时包含 undefined
    "noUncheckedIndexedAccess": true,


    // 覆盖方法必须使用 override 关键字
    "noImplicitOverride": true,


    // 允许未使用的标签
    "allowUnusedLabels": false,


    // 允许不可达代码
    "allowUnreachableCode": false,


    // 精确的可选属性类型
    "exactOptionalPropertyTypes": true
  }
}

输出配置#

outDir 和 rootDir#

{
  "compilerOptions": {
    "outDir": "./dist", // 输出目录
    "rootDir": "./src" // 源文件根目录
  }
}

声明文件#

{
  "compilerOptions": {
    "declaration": true, // 生成 .d.ts 文件
    "declarationDir": "./types", // 声明文件输出目录
    "declarationMap": true, // 生成声明文件的 source map
    "emitDeclarationOnly": true // 只生成声明文件
  }
}

Source Map#

{
  "compilerOptions": {
    "sourceMap": true, // 生成 .js.map 文件
    "inlineSourceMap": false, // 内联 source map
    "inlineSources": false, // 内联源代码
    "sourceRoot": "", // source map 中的源文件根路径
    "mapRoot": "" // source map 文件位置
  }
}

互操作性#

ES 模块互操作#

{
  "compilerOptions": {
    // 允许 import x from 'module'（模块没有默认导出时）
    "allowSyntheticDefaultImports": true,


    // 为 CommonJS 模块生成兼容代码
    "esModuleInterop": true,


    // 强制文件名大小写一致
    "forceConsistentCasingInFileNames": true
  }
}

类型检查#

{
  "compilerOptions": {
    // 跳过库文件类型检查
    "skipLibCheck": true,


    // 跳过默认库类型检查
    "skipDefaultLibCheck": true,


    // 隔离模块（每个文件独立编译）
    "isolatedModules": true,


    // 允许导入 JSON
    "resolveJsonModule": true
  }
}

配置继承#

extends#

继承其他配置文件：

tsconfig.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

常用基础配置#

tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

项目引用#

用于大型项目的增量构建：

packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}


// packages/app/tsconfig.json
{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "../shared" }
  ],
  "include": ["src/**/*"]
}


// 根目录 tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/app" }
  ]
}

常用配置模板#

Node.js 项目#

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

React 项目#

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "allowImportingTsExtensions": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

Vue 项目#

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true,
    "jsx": "preserve",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "allowImportingTsExtensions": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

库项目#

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

常见问题#

🙋 noEmit 什么时候使用？#

{
  "compilerOptions": {
    // 只进行类型检查，不生成输出
    // 适用于使用其他工具（如 Vite、esbuild）编译的项目
    "noEmit": true
  }
}

🙋 isolatedModules 的作用？#

{
  "compilerOptions": {
    // 确保每个文件可以独立编译
    // 禁用依赖类型信息的特性
    // 适用于 Babel、esbuild 等不进行类型检查的编译器
    "isolatedModules": true
  }
}


// 以下代码在 isolatedModules 下会报错
// const enum Color { Red, Green }  // ❌ const enum 不能独立编译
// export { Type } from './types';  // ❌ 仅类型导出需要 type 关键字
// export type { Type } from './types';  // ✅ 正确

🙋 如何排查配置问题？#

Terminal window
# 查看最终配置
npx tsc --showConfig


# 查看将要编译的文件
npx tsc --listFiles


# 详细诊断
npx tsc --extendedDiagnostics

总结#

配置类别关键选项用途
目标target, lib编译目标和可用 API
模块module, moduleResolution模块系统
严格strict, strictNullChecks��型检查严格程度
输出outDir, declaration输出文件配置
路径baseUrl, paths路径别名
项目references, composite多项目构建

下一篇我们将学习类型体操入门，了解高级类型编程技巧。