TSConfig 配置详解 - 构建相关

┌─────────────────────────────────────────────────────────────┐
│                    TSConfig 配置架构                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  构建相关   │ →  │ 类型检查相关 │ →  │  工程相关   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│        │                  │                  │              │
│        ▼                  ▼                  ▼              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ 源码解析    │    │ 严格检查    │    │ 项目引用    │     │
│  │ 编译转换    │    │ 逻辑检查    │    │ 增量构建    │     │
│  │ 产物输出    │    │ 交互检查    │    │ 配置继承    │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

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

// NestJS 示例
@Controller("users")
export class UserController {
  @Get()
  findAll() {
    return "This action returns all users"
  }
}

var __metadata =
  (this && this.__metadata) ||
  function (k, v) {
    if (typeof Reflect === "object" && typeof Reflect.metadata === "function")
      return Reflect.metadata(k, v)
  }
 
__decorate([Prop(), __metadata("design:type", String)], Foo.prototype, "prop", void 0)
 
__decorate(
  [
    Method(),
    __param(0, Param()),
    __metadata("design:type", Function),
    __metadata("design:paramtypes", [String]),
    __metadata("design:returntype", void 0)
  ],
  Foo.prototype,
  "handler",
  null
)

// 源代码
export const helloWorld = () => <h1>Hello world</h1>
 
// react 模式
import React from "react"
export const helloWorld = () => React.createElement("h1", null, "Hello world")
 
// preserve / react-native 模式
import React from "react"
export const helloWorld = () => <h1>Hello world</h1>
 
// react-jsx 模式（React 17+）
import { jsx as _jsx } from "react/jsx-runtime"
export const helloWorld = () => _jsx("h1", { children: "Hello world" })
 
// react-jsxdev 模式（开发环境，包含调试信息）
import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime"
const _jsxFileName = "/path/to/file.tsx"
export const helloWorld = () =>
  _jsxDEV(
    "h1",
    { children: "Hello world" },
    void 0,
    false,
    { fileName: _jsxFileName, lineNumber: 9, columnNumber: 32 },
    this
  )

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}

import { h } from "preact"
const HelloWorld = () => h("div", null, "Hello")

// 示例：使用 ES2021 的 replaceAll 方法
"linbudu".replaceAll("d", "dd")

// Web 项目推荐配置
{
  "compilerOptions": {
    "target": "ES2018",
    "lib": ["ES2018", "DOM", "DOM.Iterable"]
  }
}
 
// Node.js 项目推荐配置
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"],
    "types": ["node"]
  }
}
 
// 需要兼容 IE11
{
  "compilerOptions": {
    "target": "ES5",
    "lib": ["ES5", "DOM", "ScriptHost"]
  }
}

{
  "compilerOptions": {
    "noLib": true
  }
}

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

{
  "include": ["src/**/*", "generated/*.ts", "internal/*"]
}

{
  "include": ["src/**/*"],
  "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/file-excluded", "node_modules"]
}

┌─────────────────────────────────────────────────────────────┐
│                    文件包含解析流程                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│  │  files   │ →  │ include  │ →  │ exclude  │ → 编译文件   │
│  └──────────┘    └──────────┘    └──────────┘             │
│       │               │               │                    │
│       ▼               ▼               ▼                    │
│   精确指定        glob 匹配        排除过滤                 │
│   最高优先        批量包含        最终确定                  │
│                                                             │
│  默认排除：node_modules, bower_components, jspm_packages   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

project
├── out.ts
├── src
│   └── core.ts
└── tsconfig.json

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

// out.ts
import "src/core" // 解析为 ./src/core.ts

PROJECT
├── src
│   ├── index.ts
│   ├── app.ts
│   └── utils
│       └── helpers.ts
├── declare.d.ts
└── tsconfig.json

PROJECT
├── dist
│   ├── index.js
│   ├── app.js
│   └── utils
│       └── helpers.js

PROJECT
├── env
│   ├── env.dev.ts
│   └── env.prod.ts
├── app
│   └── index.ts
├── declare.d.ts
└── tsconfig.json

PROJECT
├── dist
│   ├── env
│   │   ├── env.dev.js
│   │   └── env.prod.js
│   └── app
│       └── index.js

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  }
}

PROJECT
├── src
│   └── locales
│       ├── zh.locale.ts
│       ├── en.locale.ts
│       └── jp.locale.ts
├── generated
│   └── messages
│       ├── main.mapper.ts
│       └── info.mapper.ts
└── tsconfig.json

{
  "compilerOptions": {
    "rootDirs": ["src/locales", "generated/messages"]
  }
}

// zh.locale.ts
import { mainMapper } from "./main.mapper" // 类型检查通过

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

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./node_modules/@team-types", "./typings"],
    "types": ["react"],
    "skipLibCheck": true
  }
}

/<project>/src/node_modules/foo.ts
/<project>/src/node_modules/foo.tsx
/<project>/src/node_modules/foo.d.ts
/<project>/node_modules/foo.ts
...
/node_modules/foo.ts

{
  "compilerOptions": {
    "moduleSuffixes": [".ios", ".native", ""]
  }
}

src/
├── utils.ios.ts     // iOS 平台实现
├── utils.android.ts // Android 平台实现
├── utils.native.ts  // 其他原生平台实现
└── utils.ts         // Web 平台实现

import { utils } from "./utils"
// iOS: 加载 utils.ios.ts
// Android: 加载 utils.android.ts
// Web: 加载 utils.ts

{
  "compilerOptions": {
    "noResolve": true
  }
}

// 即使这个文件存在，也不会被包含在编译中
import { foo } from "./other"
 
/// <reference path="./other.d.ts" />  // 三斜线指令也会被忽略

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

// 原路径
import { helper } from "../../../utils/helper"
 
// 使用别名
import { helper } from "@/utils/helper"

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

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

{
  "repo": "TypeScript",
  "dry": false,
  "debug": false
}

import settings from "./settings.json"
 
settings.debug // 类型为 boolean
settings.repo // 类型为 "TypeScript"（字面量类型）
 
settings.dry === 2 // ❌ 类型错误

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

src
├── core
│   └── handler.ts
└── index.ts

dist
├── core
│   ├── handler.js
│   └── handler.d.ts
├── index.js
└── index.d.ts

{
  "compilerOptions": {
    "module": "AMD",
    "outFile": "./dist/bundle.js"
  }
}

// 源代码
export const name = "TypeScript"
export function greet() {
  return "Hello"
}

// commonjs
"use strict"
Object.defineProperty(exports, "__esModule", { value: true })
exports.greet = greet
exports.name = void 0
exports.name = "TypeScript"
function greet() {
  return "Hello"
}
 
// es6 / es2015 / es2020 / es2022 / esnext
export const name = "TypeScript"
export function greet() {
  return "Hello"
}
 
// amd
define(["require", "exports"], function (require, exports) {
  "use strict"
  Object.defineProperty(exports, "__esModule", { value: true })
  exports.greet = exports.name = void 0
  exports.name = "TypeScript"
  function greet() {
    return "Hello"
  }
  exports.greet = greet
})
 
// umd
;(function (factory) {
  if (typeof module === "object" && typeof module.exports === "object") {
    var v = factory(require, exports)
    if (v !== undefined) module.exports = v
  } else if (typeof define === "function" && define.amd) {
    define(["require", "exports"], factory)
  }
})(function (require, exports) {
  "use strict"
  Object.defineProperty(exports, "__esModule", { value: true })
  exports.greet = exports.name = void 0
  exports.name = "TypeScript"
  function greet() {
    return "Hello"
  }
  exports.greet = greet
})

// Node.js 项目
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS"
  }
}
 
// 浏览器项目（配合打包工具）
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext"
  }
}
 
// Node.js ESM 项目
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

const enum Direction {
  Up = "UP",
  Down = "DOWN"
}
 
console.log(Direction.Up)

console.log("UP" /* Direction.Up */)

{
  "compilerOptions": {
    "preserveConstEnums": true
  }
}

var Direction
;(function (Direction) {
  Direction["Up"] = "UP"
  Direction["Down"] = "DOWN"
})(Direction || (Direction = {}))
 
console.log(Direction.Up)

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

# 使用 ESBuild 构建代码，tsc 仅做类型检查
tsc --noEmit
esbuild src/index.ts --bundle --outfile=dist/bundle.js

{
  "compilerOptions": {
    "noEmitOnError": true
  }
}

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./dist/types"
  }
}

// src/index.ts
export interface User {
  id: string
  name: string
}
 
export function createUser(name: string): User {
  return { id: crypto.randomUUID(), name }
}

export interface User {
  id: string
  name: string
}
export declare function createUser(name: string): User

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true
  }
}

{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true
  }
}

# tsc 生成声明文件
tsc --emitDeclarationOnly
 
# ESBuild 编译 JavaScript
esbuild src/index.ts --outfile=dist/index.js

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

dist/
├── index.js
└── index.js.map

{
  "compilerOptions": {
    "inlineSourceMap": true
  }
}

// dist/index.js
console.log("Hello")
//# sourceMappingURL=data:application/json;base64,...

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

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

// 源代码
/** 用户信息 */
interface User {
  /** 用户 ID */
  id: string
  /** 用户名 */
  name: string
}
 
// 输出（removeComments: true）
interface User {
  id
  name
}

{
  "compilerOptions": {
    "importHelpers": true
  }
}

// 源代码
class Foo {
  @decorator
  method() {}
}

// 未启用 importHelpers（每个文件都有辅助函数）
var __decorate =
  (this && this.__decorate) ||
  function (decorators, target, key, desc) {
    // ... 大量代码
  }
class Foo {
  method() {}
}
Foo = __decorate([decorator], Foo)
 
// 启用 importHelpers（从 tslib 导入）
var tslib_1 = require("tslib")
class Foo {
  method() {}
}
Foo = tslib_1.__decorate([decorator], Foo)

npm install tslib

{
  "compilerOptions": {
    "target": "ES5",
    "downlevelIteration": true
  }
}

// 源代码
const arr = [1, 2, 3]
for (const item of arr) {
  console.log(item)
}
const copy = [...arr]

// 未启用 downlevelIteration
var arr = [1, 2, 3]
for (var _i = 0, arr_1 = arr; _i < arr_1.length; _i++) {
  var item = arr_1[_i]
  console.log(item)
}
var copy = arr.slice()
 
// 启用 downlevelIteration（支持自定义迭代器）
var __values =
  (this && this.__values) ||
  function (o) {
    // ... 迭代器辅助函数
  }
var arr = [1, 2, 3]
try {
  for (var arr_1 = __values(arr), arr_1_1 = arr_1.next(); !arr_1_1.done; arr_1_1 = arr_1.next()) {
    var item = arr_1_1.value
    console.log(item)
  }
} catch (e_1) {
  /* ... */
}
var copy = __spreadArray([], __read(arr), false)

{
  "compilerOptions": {
    "newLine": "lf" // 或 "crlf"
  }
}

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "moduleResolution": "node",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

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

// 源代码
export const fn = async () => {
  await Promise.resolve()
}

// vite.config.js
export default {
  resolve: {
    alias: {
      "@": "/path/to/src"
    }
  }
}
 
// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src")
    }
  }
}

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

// 方案一：使用普通枚举
enum Direction {
  Up,
  Down
}
 
// 方案二：启用 preserveConstEnums
const enum Direction {
  Up,
  Down
}
// tsconfig.json: "preserveConstEnums": true

┌─────────────────────────────────────────────────────────────┐
│                    TSConfig 配置原则                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 渐进式严格                                              │
│     • 新项目：直接启用 strict: true                         │
│     • 老项目：逐步启用 noImplicitAny 等选项                 │
│                                                             │
│  2. 环境匹配                                                │
│     • Web 项目：target 和 module 配合打包工具               │
│     • Node.js 项目：使用 CommonJS 或 NodeNext               │
│                                                             │
│  3. 开发体验                                                │
│     • 启用 sourceMap 便于调试                               │
│     • 启用 declaration 便于类型提示                         │
│                                                             │
│  4. 性能优化                                                │
│     • 启用 skipLibCheck 加速编译                            │
│     • 使用 incremental 增量编译                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

{
  "compilerOptions": {
    // ❌ 错误：target 和 lib 不匹配
    "target": "ES5",
    "lib": ["ES2020"]  // ES5 目标无法使用 ES2020 API
 
    // ❌ 错误：module 和 outFile 不兼容
    "module": "CommonJS",
    "outFile": "./dist/bundle.js"  // CommonJS 不支持 outFile
 
    // ❌ 错误：paths 缺少 baseUrl
    "paths": {
      "@/*": ["src/*"]  // 需要 baseUrl
    }
  }
}