TSConfig 配置详解 - 检查与工程

┌─────────────────────────────────────────────────────────────┐
│                    检查与工程配置架构                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   检查相关配置                        │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  允许类    │  禁止类    │  严格检查   │  其他检查    │   │
│  │  allowXxx  │  noXxx     │  strict     │  skipLib    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   工程相关配置                        │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  项目引用  │  增量构建  │  配置继承   │  兼容性      │   │
│  │  references│ incremental│  extends   │  interop    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

{
  "compilerOptions": {
    "allowUmdGlobalAccess": true
  }
}

<!-- 通过 CDN 引入 jQuery -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

// 无需导入，直接使用
// 默认情况会报错，启用 allowUmdGlobalAccess 后可用
$(() => {
  console.log("jQuery is ready!")
})

;(function (global, factory) {
  // 尝试使用 CommonJS
  if (typeof module === "object" && typeof module.exports === "object") {
    var v = factory(require, exports)
    if (v !== void 0) module.exports = v
  }
  // 尝试使用 AMD
  else if (typeof define === "function" && define.amd) {
    define(["require", "exports"], factory)
  }
  // 兜底，使用全局变量挂载
  else {
    ;((global = global || self), (global.jquery = factory()))
  }
})(function (require, exports) {
  "use strict"
  // 模块实现
})

function foo() {
  return 599
  console.log("Dead Code") // Unreachable code
}

function bar() {
  throw new Error("Oops!")
  console.log("Dead Code") // Unreachable code
}

function baz() {
  process.exit(0)
  console.log("Dead Code") // Unreachable code
}

{
  "compilerOptions": {
    "allowUnreachableCode": false
  }
}

someLabel: {
  statement
}

function verifyAge(age: number) {
  if (age > 18) {
    // 本意是返回对象，但忘记了 return
    // 导致这里被解析为 Label
    verified: true // Unused label
  }
}

{
  "compilerOptions": {
    "allowUnusedLabels": false
  }
}

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

// ❌ 启用 noImplicitAny 后报错
function fn(s) {
  // Parameter 's' implicitly has an 'any' type.
  console.log(s.includes("linbudu"))
}

// ✅ 显式标注类型
function fn(s: string) {
  console.log(s.includes("linbudu"))
}

// ✅ 显式标注为 any（不推荐）
function fn(s: any) {
  console.log(s.includes("linbudu"))
}

// ❌ 隐式 any
export function parseConfig(config) {
  return JSON.parse(config)
}

// ✅ 明确类型
interface AppConfig {
  apiUrl: string
  timeout: number
}

export function parseConfig(config: string): AppConfig {
  return JSON.parse(config)
}

{
  "compilerOptions": {
    "useUnknownInCatchVariables": true
  }
}

// 默认行为（error 为 any）
try {
  // ...
} catch (err) {
  console.log(err.message) // ✅ 可以访问任意属性
  console.log(err.foo) // ✅ 不会报错
}

// 启用 useUnknownInCatchVariables 后（error 为 unknown）
try {
  // ...
} catch (err: unknown) {
  console.log(err.message) // ❌ 'err' is of type 'unknown'

  // ✅ 需要先进行类型收窄
  if (err instanceof Error) {
    console.log(err.message)
  }

  if (err instanceof NetworkError) {
    console.log(err.code)
  }

  // ✅ 使用类型断言
  console.log((err as Error).message)
}

class NetworkError extends Error {
  constructor(
    message: string,
    public code: number
  ) {
    super(message)
  }
}

class AuthError extends Error {
  constructor(
    message: string,
    public statusCode: number
  ) {
    super(message)
  }
}

try {
  // ...
} catch (err: unknown) {
  if (err instanceof NetworkError) {
    console.error(`Network error: ${err.code}`)
  } else if (err instanceof AuthError) {
    console.error(`Auth error: ${err.statusCode}`)
  } else if (err instanceof Error) {
    console.error(`Unknown error: ${err.message}`)
  } else {
    console.error("An unknown error occurred")
  }
}

{
  "compilerOptions": {
    "noFallthroughCasesInSwitch": true
  }
}

const a: number = 0

switch (a) {
  case 0:
    console.log("zero")
  // ❌ Fallthrough case in switch
  case 1:
    console.log("one")
  // ❌ Fallthrough case in switch
  case 2:
    console.log("two")
    break
}

// ✅ 正确写法
switch (a) {
  case 0:
    console.log("zero")
    break
  case 1:
    console.log("one")
    break
  case 2:
    console.log("two")
    break
}

// 使用 // falls through 注释表明有意为之
switch (a) {
  case 0:
  case 1:
  case 2:
    console.log("0, 1, or 2")
    break
}

// 或使用 // falls through
switch (a) {
  case 0:
    console.log("zero")
  // falls through
  case 1:
    console.log("one")
    break
}

{
  "compilerOptions": {
    "noImplicitOverride": true
  }
}

class Base {
  print() {
    console.log("Base")
  }
}

class Derived extends Base {
  // ❌ 错误：需要使用 override 关键字
  print() {
    console.log("Derived")
  }
}

class DerivedCorrect extends Base {
  // ✅ 正确
  override print() {
    console.log("DerivedCorrect")
  }
}

class BaseService {
  getData() {
    return fetch("/api/data")
  }
}

class UserService extends BaseService {
  // 如果基类中没有 getData 方法，这里会报错
  // 避免拼写错误或基类方法被删除
  override getData() {
    return fetch("/api/users")
  }
}

{
  "compilerOptions": {
    "noImplicitReturns": true
  }
}

// ❌ 错误：Not all code paths return a value
function handle(color: "blue" | "black"): string {
  if (color === "blue") {
    return "beats"
  } else {
    ;("bose") // 忘记 return
  }
}

// ✅ 正确
function handle(color: "blue" | "black"): string {
  if (color === "blue") {
    return "beats"
  } else {
    return "bose"
  }
}

// ✅ 提前返回
function validateAge(age: number): boolean {
  if (age < 0) {
    return false
  }
  if (age > 150) {
    return false
  }
  return true
}

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

// ❌ 错误：'this' implicitly has type 'any'
function foo(name: string) {
  this.name = name // this 类型不明确
}

// ✅ 显式声明 this 类型
function foo(this: any, name: string) {
  this.name = name
}

// ✅ 更好的做法：使用具体类型
interface Person {
  name: string
  setName(name: string): void
}

const person: Person = {
  name: "",
  setName(this: Person, name: string) {
    this.name = name
  }
}

class Handler {
  private value = 42

  // ✅ 箭头函数自动绑定 this
  method = () => {
    console.log(this.value)
  }

  // ❌ 需要显式声明 this 类型
  method2(this: Handler) {
    console.log(this.value)
  }
}

{
  "compilerOptions": {
    "noPropertyAccessFromIndexSignature": true
  }
}

interface AllStringTypes {
  name: string // 已知属性
  [key: string]: string // 索引签名
}

const obj: AllStringTypes = { name: "TypeScript" }

// ✅ 访问已知属性
obj.name

// ❌ 错误：不能通过点语法访问索引签名属性
obj.unknownProp

// ✅ 使用括号语法（提醒这是未知属性）
obj["unknownProp"]

{
  "compilerOptions": {
    "noUncheckedIndexedAccess": true
  }
}

interface StringArray {
  [index: number]: string
}

const arr: StringArray = ["a", "b", "c"]

// 默认情况
const item1: string = arr[0] // ✅ 类型为 string

// 启用 noUncheckedIndexedAccess 后
const item2 = arr[0] // 类型为 string | undefined
const item3 = arr[99] // 类型为 string | undefined

// ✅ 需要先检查
if (arr[0] !== undefined) {
  console.log(arr[0].toUpperCase())
}

// ✅ 使用非空断言（确定存在时）
console.log(arr[0]!.toUpperCase())

const list = ["linbudu", "599"]

// 启用 noUncheckedIndexedAccess 后
const first = list[0] // string | undefined
const hundredth = list[99] // string | undefined

// ✅ 更安全的访问
const safeFirst = list.at(0) // string | undefined（使用 at 方法）

// 需要空值检查
if (first) {
  console.log(first.toUpperCase())
}

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

// ❌ 'unusedVar' is declared but its value is never read
const unusedVar = 42

// ❌ 'unusedParam' is declared but its value is never read
function foo(unusedParam: string, usedParam: number) {
  console.log(usedParam)
}

// ✅ 使用下划线前缀表示有意忽略
function foo(_unusedParam: string, usedParam: number) {
  console.log(usedParam)
}

// ✅ 解构时忽略某些属性
const { value, ...rest } = obj
console.log(rest)

// ✅ 使用下划线前缀
const { value, ..._rest } = obj
console.log(value)

{
  "compilerOptions": {
    "exactOptionalPropertyTypes": true
  }
}

interface ITheme {
  prefer?: "dark" | "light"
}

declare const theme: ITheme

// 默认情况：可选属性类型为 "dark" | "light" | undefined
theme.prefer = "dark" // ✅
theme.prefer = "light" // ✅
theme.prefer = undefined // ✅

// 启用 exactOptionalPropertyTypes 后
theme.prefer = "dark" // ✅
theme.prefer = "light" // ✅
theme.prefer = undefined // ❌ Type 'undefined' is not assignable to type '"dark" | "light"'

// ✅ 显式声明 undefined
interface IThemeStrict {
  prefer?: "dark" | "light" | undefined
}

theme.prefer = undefined // ✅

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

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

function fn(x: string): number {
  return parseInt(x)
}

// ✅ 正确
const n1 = fn.call(undefined, "10")

// ❌ 类型 'boolean' 的参数不能赋给类型 'string' 的参数
const n2 = fn.call(undefined, false)

// ❌ 类型 'number' 的参数不能赋给类型 'string' 的参数
const n3 = fn.apply(undefined, [10])

function fn(x: string) {
  console.log("Hello, " + x.toLowerCase())
}

type StringOrNumberFunc = (ns: string | number) => void

// ❌ 不能将类型 'string | number' 分配给类型 'string'
let func: StringOrNumberFunc = fn

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

// ❌ 关闭 strictNullChecks 时
const tmp1: string = null // ✅ 不报错（危险）
const tmp2: string = undefined // ✅ 不报错（危险）

// ✅ 启用 strictNullChecks 后
const tmp3: string = null // ❌ 报错
const tmp4: string = undefined // ❌ 报错

// ✅ 正确的类型标注
const tmp5: string | null = null
const tmp6: string | undefined = undefined

const matcher: string = "budu"
const list = ["linbudu", "599"]

// find 返回 string | undefined
const target = list.find((u) => u.includes(matcher))

// ❌ 启用 strictNullChecks 后报错
console.log(target.replace("budu", "wuhu"))
// 对象可能为"未定义"。

// ✅ 正确的处理方式
if (target) {
  console.log(target.replace("budu", "wuhu"))
}

// 或使用可选链
console.log(target?.replace("budu", "wuhu"))

// 或使用非空断言（确定存在时）
console.log(target!.replace("budu", "wuhu"))

class Foo {
  prop1: number = 599
  prop2: number
  // ❌ 属性 'prop3' 没有初始化表达式，且未在构造函数中明确赋值
  prop3: number

  constructor(public prop4: number) {
    this.prop2 = prop4
  }
}

// ✅ 正确写法
class FooCorrect {
  prop1: number = 599
  prop2: number
  prop3: number

  constructor(public prop4: number) {
    this.prop2 = prop4
    this.prop3 = 0
  }
}

class Foo {
  prop1: number = 599
  prop2: number
  prop3: number // ❌ 报错

  constructor(public prop4: number) {
    this.prop2 = prop4
    this.init() // 在其他方法中初始化
  }

  init() {
    this.prop3 = 599
  }
}

// ✅ 解决方案 1：使用非空断言
class Foo1 {
  prop3!: number // 确定会被初始化
}

// ✅ 解决方案 2：使用可选属性
class Foo2 {
  prop3?: number // 可选，允许 undefined
}

// ✅ 解决方案 3：显式声明 undefined
class Foo3 {
  prop3: number | undefined
}

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

/// <reference no-default-lib="true"/>

PROJECT
├── app
│   ├── index.ts
│   └── tsconfig.json
├── core
│   ├── index.ts
│   └── tsconfig.json
├── ui
│   ├── index.ts
│   └── tsconfig.json
├── utils
│   ├── index.ts
│   └── tsconfig.json
└── tsconfig.base.json

┌─────────────────────────────────────────────────────────────┐
│                    项目依赖关系                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                      ┌─────┐                               │
│                      │ app │                               │
│                      └──┬──┘                               │
│                         │                                   │
│            ┌────────────┼────────────┐                     │
│            │            │            │                     │
│            ▼            ▼            ▼                     │
│        ┌─────┐     ┌─────┐     ┌─────┐                   │
│        │ ui  │     │ core│     │utils│                   │
│        └──┬──┘     └──┬──┘     └─────┘                   │
│           │            │                                  │
│           └─────┬──────┘                                  │
│                 │                                          │
│                 ▼                                          │
│             ┌─────┐                                       │
│             │utils│                                       │
│             └─────┘                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

// app/tsconfig.json
{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "../dist/app",
    "rootDir": "."
  },
  "references": [
    { "path": "../core" },
    { "path": "../ui" },
    { "path": "../utils" }
  ]
}

// core/tsconfig.json
{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "../dist/core",
    "rootDir": "."
  },
  "references": [
    { "path": "../utils" }
  ]
}

// utils/tsconfig.json
{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "../dist/utils",
    "rootDir": "."
  }
  // 无 references，因为它是基础依赖
}

// utils/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true
  }
}

# 构建所有项目
tsc -b

# 构建特定项目
tsc -b app

# 强制重新构建
tsc -b --force

# 增量构建（仅构建变更的项目）
tsc -b

// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node"
  }
}

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

// packages/shared/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true
  }
}

{
  "extends": "@tsconfig/recommended/tsconfig.json"
}

npm install -D @tsconfig/node18

{
  "extends": "@tsconfig/node18/tsconfig.json"
}

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./dist/.tsbuildinfo"
  }
}

dist/
├── index.js
├── index.d.ts
└── .tsbuildinfo    # 增量编译信息

{
  "compilerOptions": {
    "composite": true, // 自动启用 incremental
    "incremental": true
  }
}

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./build/.tsbuildinfo"
  }
}

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

// CommonJS 模块导出方式
// react/index.js
module.exports = React

// 默认情况下导入
import React from "react" // ❌ 不可用
import * as React from "react" // ✅ 可用

// 启用 esModuleInterop 后
import React from "react" // ✅ 可用

// 未启用 esModuleInterop
var react_1 = require("react")
console.log(react_1.default) // undefined

// 启用 esModuleInterop
var __importDefault =
  (this && this.__importDefault) ||
  function (mod) {
    return mod && mod.__esModule ? mod : { default: mod }
  }
var react_1 = __importDefault(require("react"))
console.log(react_1.default) // React 对象

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

// utils.ts - 没有默认导出
export const foo = "foo"
export const bar = "bar"

// main.ts
// 未启用时：❌ 错误
// 启用后：✅ 允许（仅类型检查，运行时仍需处理）
import utils from "./utils"

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

// legacy.js
module.exports = {
  oldFunction: function () {
    return "legacy"
  }
}

// main.ts
import { oldFunction } from "./legacy" // ✅ 允许导入

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true // 对 JS 文件也进行类型检查
  }
}

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

// utils.js
/**
 * @param {string} name
 * @returns {string}
 */
function greet(name) {
  return `Hello, ${name}`
}

// 错误检测
greet(123) // ❌ 类型错误

{
  "compilerOptions": {
    "allowJs": true,
    "maxNodeModuleJsDepth": 1
  }
}

{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": true, // 第一步
    "strictNullChecks": true // 第二步
  }
}

1. noImplicitAny      → 消除隐式 any
2. strictNullChecks   → 处理 null/undefined
3. noUnusedLocals     → 清理未使用变量
4. noUnusedParameters → 清理未使用参数
5. strict             → 全部启用

{
  "compilerOptions": {
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,
    "incremental": true
  }
}

{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "incremental": true
  }
}

// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "composite": true,
    "incremental": true,
    "declaration": true,
    "declarationMap": true
  }
}

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

┌─────────────────────────────────────────────────────────────┐
│                    检查配置决策树                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  项目类型？                                                  │
│       │                                                     │
│       ├── 新项目 → strict: true                             │
│       │                                                     │
│       └── 老项目 → 渐进式启用                                │
│               │                                             │
│               ├── 第一步：noImplicitAny                     │
│               ├── 第二步：strictNullChecks                  │
│               ├── 第三步：noUnusedLocals/Parameters         │
│               └── 最终：strict: true                        │
│                                                             │
│  项目规模？                                                  │
│       │                                                     │
│       ├── 大型项目 → Project References + incremental       │
│       │                                                     │
│       └── 中小型项目 → incremental                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

// tsconfig.base.json — 公共基础配置
{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "strict": true,
        "composite": true  // ⚠️ 必须开启，标记此项目可被引用
    }
}

// packages/core/tsconfig.json — 子项目配置
{
    "extends": "../../tsconfig.base.json",
    "compilerOptions": {
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src"]
}

// packages/app/tsconfig.json — 引用其他子项目
{
    "extends": "../../tsconfig.base.json",
    "compilerOptions": {
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src"],
    "references": [
        { "path": "../core" }  // 声明对 core 项目的依赖
    ]
}

# 增量编译：只重新编译变更的部分
tsc --build packages/core    # 首次编译，生成 .tsbuildinfo
tsc --build packages/core    # 无变更，跳过编译（毫秒级）

# 修改 core/src/index.ts 后
tsc --build packages/core    # 增量编译，只处理变更文件

# 强制全量重新编译
tsc --build packages/core --force

# 清理构建产物
tsc --build packages/core --clean

// tsconfig.json 中控制 buildinfo
{
    "compilerOptions": {
        "incremental": true,              // 启用增量编译
        "tsBuildInfoFile": "./.tsbuildinfo" // 指定缓存文件路径（默认在 outDir 中）
    }
}

# ❌ 普通编译不会处理 references
tsc -p packages/app/tsconfig.json

# ✅ 使用 --build 模式
tsc --build packages/app

# --build 模式的行为：
# 1. 自动找到对应目录下的 tsconfig.json
# 2. 按依赖顺序构建所有引用的项目
# 3. 只重新编译有变更的项目
# 4. 生成 .d.ts 和 .tsbuildinfo 文件

monorepo/
├── tsconfig.base.json
├── packages/
│   ├── core/
│   │   ├── tsconfig.json     # composite: true
│   │   ├── src/
│   │   └── dist/
│   ├── utils/
│   │   ├── tsconfig.json     # composite: true, references: [../core]
│   │   ├── src/
│   │   └── dist/
│   └── app/
│       ├── tsconfig.json     # references: [../core, ../utils]
│       ├── src/
│       └── dist/
└── tsconfig.json             # 顶层配置，references 引用所有子项目

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