TypeScript 配置文件详解

tsconfig.json 是 TypeScript 项目的配置文件，用于指定编译选项和项目设置。

创建配置文件

自动生成

bash

# 在项目根目录运行
tsc --init

这会创建一个包含所有选项的 tsconfig.json 文件，并附有注释说明。

手动创建

在项目根目录创建 tsconfig.json 文件：

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs"
  }
}

配置选项详解

基础选项

target

指定编译后的 JavaScript 目标版本。

json

{
  "compilerOptions": {
    "target": "ES2020"  // ES3, ES5, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext
  }
}

module

指定模块系统。

json

{
  "compilerOptions": {
    "module": "commonjs"  // none, commonjs, amd, system, umd, es6, es2015, es2020, esnext
  }
}

lib

指定要包含的库文件。

json

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  }
}

常用库：

ES5, ES2015, ES2020 等：ECMAScript 标准库
DOM：浏览器 DOM API
DOM.Iterable：可迭代的 DOM API
WebWorker：Web Worker API
ScriptHost：Windows Script Host API

outDir

指定编译输出目录。

json

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

rootDir

指定源文件根目录。

json

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

outFile

将所有输出合并为一个文件（仅适用于 AMD 或 System 模块）。

json

{
  "compilerOptions": {
    "outFile": "./dist/bundle.js"
  }
}

类型检查选项

strict

启用所有严格类型检查选项。

json

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

等同于同时启用：

strictNullChecks
strictFunctionTypes
strictBindCallApply
strictPropertyInitialization
noImplicitThis
alwaysStrict

strictNullChecks

启用严格的 null 检查。

json

{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

// strictNullChecks: false
let x: number;
x = null;  // ✅ 允许

// strictNullChecks: true
let x: number;
x = null;  // ❌ 错误：不能将类型 "null" 分配给类型 "number"

noImplicitAny

禁止隐式 any 类型。

json

{
  "compilerOptions": {
    "noImplicitAny": true
  }
}

// noImplicitAny: false
function fn(s) {  // s 隐式为 any
    return s;
}

// noImplicitAny: true
function fn(s) {  // ❌ 错误：参数 "s" 隐式具有 "any" 类型
    return s;
}

strictFunctionTypes

启用严格的函数类型检查。

json

{
  "compilerOptions": {
    "strictFunctionTypes": true
  }
}

strictPropertyInitialization

确保类的属性已初始化。

json

{
  "compilerOptions": {
    "strictPropertyInitialization": true
  }
}

class User {
    name: string;  // ❌ 错误：属性 "name" 没有初始化
}

// 解决方案
class User {
    name!: string;  // 使用非空断言
    // 或
    name: string = "";  // 提供默认值
    // 或
    name?: string;  // 设为可选
}

noImplicitThis

禁止隐式 this。

json

{
  "compilerOptions": {
    "noImplicitThis": true
  }
}

alwaysStrict

以严格模式解析并发出代码。

json

{
  "compilerOptions": {
    "alwaysStrict": true
  }
}

模块解析选项

moduleResolution

指定模块解析策略。

json

{
  "compilerOptions": {
    "moduleResolution": "node"  // "node" 或 "classic"
  }
}

baseUrl

设置模块解析的基础目录。

json

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

// 使用 baseUrl
import { utils } from "utils/helper";  // 从 src/utils/helper 解析

paths

设置模块名到路径的映射。

json

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

// 使用 paths
import { Button } from "@/components/Button";
import { format } from "utils/format";

typeRoots

指定类型声明文件的根目录。

json

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  }
}

types

指定要包含的类型声明包。

json

{
  "compilerOptions": {
    "types": ["node", "express", "jest"]
  }
}

resolveJsonModule

允许导入 JSON 文件。

json

{
  "compilerOptions": {
    "resolveJsonModule": true
  }
}

import config from "./config.json";

输出选项

declaration

生成声明文件（.d.ts）。

json

{
  "compilerOptions": {
    "declaration": true
  }
}

declarationMap

为声明文件生成 source map。

json

{
  "compilerOptions": {
    "declarationMap": true
  }
}

sourceMap

生成 source map 文件。

json

{
  "compilerOptions": {
    "sourceMap": true
  }
}

removeComments

移除注释。

json

{
  "compilerOptions": {
    "removeComments": true
  }
}

noEmit

不生成输出文件（仅进行类型检查）。

json

{
  "compilerOptions": {
    "noEmit": true
  }
}

emitDeclarationOnly

仅生成声明文件，不生成 JavaScript 文件。

json

{
  "compilerOptions": {
    "emitDeclarationOnly": true
  }
}

其他选项

esModuleInterop

启用 ES 模块互操作性。

json

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

// esModuleInterop: false
import * as express from "express";  // 必须使用这种方式

// esModuleInterop: true
import express from "express";  // 可以使用这种方式

allowSyntheticDefaultImports

允许从没有默认导出的模块进行默认导入。

json

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true
  }
}

skipLibCheck

跳过库文件的类型检查（加快编译速度）。

json

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

forceConsistentCasingInFileNames

强制文件名大小写一致。

json

{
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  }
}

allowJs

允许编译 JavaScript 文件。

json

{
  "compilerOptions": {
    "allowJs": true
  }
}

checkJs

在 JavaScript 文件中启用类型检查。

json

{
  "compilerOptions": {
    "checkJs": true
  }
}

文件包含和排除

include

指定要包含的文件。

json

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

exclude

指定要排除的文件。

json

{
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts"
  ]
}

files

明确指定要编译的文件列表。

json

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

继承配置

使用 extends 继承其他配置文件。

json

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

项目引用

使用 references 配置项目引用（用于 monorepo）。

json

{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/utils" }
  ]
}

完整配置示例

基础项目配置

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020", "DOM"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

库项目配置

json

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

前端项目配置（Vue/React）

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",  // 或 "preserve" for Vue
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "allowJs": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

最佳实践

启用严格模式：始终启用 strict: true 以获得最佳类型安全
使用路径别名：配置 paths 简化导入路径
合理设置 target：根据目标环境选择合适的 ES 版本
启用 source map：开发时启用 source map 便于调试
排除不必要的文件：使用 exclude 排除测试文件和构建产物
使用继承：在 monorepo 中使用 extends 共享配置

最后更新：2025年

TypeScript 配置文件详解 ​

创建配置文件 ​

自动生成 ​

手动创建 ​

配置选项详解 ​

基础选项 ​

target ​

module ​

lib ​

outDir ​

rootDir ​

outFile ​

类型检查选项 ​

strict ​

strictNullChecks ​

noImplicitAny ​

strictFunctionTypes ​

strictPropertyInitialization ​

noImplicitThis ​

alwaysStrict ​

模块解析选项 ​

moduleResolution ​

baseUrl ​

paths ​

typeRoots ​

types ​

resolveJsonModule ​

输出选项 ​

declaration ​

declarationMap ​

sourceMap ​

removeComments ​

noEmit ​

emitDeclarationOnly ​

其他选项 ​

esModuleInterop ​

allowSyntheticDefaultImports ​

skipLibCheck ​

forceConsistentCasingInFileNames ​

allowJs ​

checkJs ​

文件包含和排除 ​

include ​

exclude ​

files ​

继承配置 ​

项目引用 ​

完整配置示例 ​

基础项目配置 ​

库项目配置 ​

前端项目配置（Vue/React） ​

最佳实践 ​

TypeScript 配置文件详解

创建配置文件

自动生成

手动创建

配置选项详解

基础选项

target

module

lib

outDir

rootDir

outFile

类型检查选项

strict

strictNullChecks

noImplicitAny

strictFunctionTypes

strictPropertyInitialization

noImplicitThis

alwaysStrict

模块解析选项

moduleResolution

baseUrl

paths

typeRoots

types

resolveJsonModule

输出选项

declaration

declarationMap

sourceMap

removeComments

noEmit

emitDeclarationOnly

其他选项

esModuleInterop

allowSyntheticDefaultImports

skipLibCheck

forceConsistentCasingInFileNames

allowJs

checkJs

文件包含和排除

include

exclude

files

继承配置

项目引用

完整配置示例

基础项目配置

库项目配置

前端项目配置（Vue/React）

最佳实践