[!info] related notes

• 所属 MOC: TypeScript MOC
• 总览页: TypeScript
• 相关概念: tsc, TypeScript 中的 baseUrl 与 paths, TypeScript 中的 module, TypeScript 中的 moduleResolution, TypeScript 中的 strict
• 关系笔记: TypeScript、tsc、tsconfig 与 tsserver 的关系
• 工程实践: Monorepo 中的 tsconfig 实践

tsconfig 使用详解

基础概念

tsconfig.json 是 TypeScript 编译器选项与文件边界的配置文件，用来定义一个 TypeScript program 应该如何被理解、检查和构建。

使用指南

单包项目的最小例子

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

Monorepo 示例

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

按知识结构看常见选项

program 边界与输出结构

• TypeScript 中的 rootDir
• TypeScript 中的 outDir
• TypeScript 中的 noEmit

类型检查基线

• 这些选项回答的是“这个项目以多严格的类型规则、什么语法目标、什么标准库类型和什么 JSX emit 策略被理解”。
• TypeScript 中的 strict
• TypeScript 中的 noImplicitAny
• TypeScript 中的 noImplicitThis
• TypeScript 中的 strictNullChecks
• TypeScript 中的 strictFunctionTypes
• TypeScript 中的 strictBindCallApply
• TypeScript 中的 strictBuiltinIteratorReturn
• TypeScript 中的 alwaysStrict
• TypeScript 中的 strictPropertyInitialization
• TypeScript 中的 noUncheckedIndexedAccess
• TypeScript 中的 noPropertyAccessFromIndexSignature
• TypeScript 中的 exactOptionalPropertyTypes
• TypeScript 中的 useUnknownInCatchVariables
• TypeScript 中的 noImplicitOverride
• TypeScript 中的 target
• TypeScript 中的 lib
• TypeScript 中的 jsx 编译选项
• TypeScript 中的 jsxImportSource
• TypeScript 中的 useDefineForClassFields

控制流与代码卫生

• TypeScript 中的 noImplicitReturns
• TypeScript 中的 noFallthroughCasesInSwitch
• TypeScript 中的 noUnusedLocals
• TypeScript 中的 noUnusedParameters
• TypeScript 中的 allowUnreachableCode
• TypeScript 中的 allowUnusedLabels

JS 共存与迁移

• TypeScript 中的 allowJs
• TypeScript 中的 checkJs

全局类型与声明文件边界

• TypeScript 中的 types 编译选项
• TypeScript 中的 typeRoots
• TypeScript 中的 skipLibCheck

声明与项目构建

• TypeScript 中的 declaration 与 declarationMap
• TypeScript 中的 declarationDir
• TypeScript 中的 emitDeclarationOnly
• TypeScript 中的 composite
• TypeScript 中的 references
• TypeScript 中的 incremental
• TypeScript 中的 tsBuildInfoFile

模块系统与模块解析

• TypeScript 中的 module
• TypeScript 中的 moduleDetection
• TypeScript 中的 moduleResolution
• TypeScript 中的 nodenext 与 bundler
• TypeScript 中 module 与 moduleResolution 的关系
• Node、bundler 与 TypeScript 模块解析的关系
• TypeScript 中的 customConditions
• TypeScript 中的 resolvePackageJsonExports
• TypeScript 中的 resolvePackageJsonImports
• TypeScript 中的 moduleSuffixes
• TypeScript 中的 resolveJsonModule
• TypeScript 中的 allowImportingTsExtensions
• TypeScript 中的 rewriteRelativeImportExtensions

模块互操作与单文件转译

• TypeScript 中的 esModuleInterop
• TypeScript 中的 allowSyntheticDefaultImports
• TypeScript 中的 verbatimModuleSyntax
• TypeScript 中的 isolatedModules

已被替代的旧模块 emit 选项

• TypeScript 中的 importsNotUsedAsValues（已废弃）
• TypeScript 中的 preserveValueImports（已废弃）

路径映射与虚拟目录

• TypeScript 中的 rootDirs
• TypeScript 中的 baseUrl
• TypeScript 中的 paths
• TypeScript 中的 baseUrl 与 paths

经验总结

• 单仓项目先关注 include/exclude、strict、module、target 这些基本边界。
• monorepo 项目再进一步关注 composite、declaration、references 与包边界。
• tsconfig 越往后越不适合继续堆在一篇总览里；一旦出现模块解析、产物目录、project references 这些稳定主题，就值得拆成原子页。

参考信息

• TypeScript 官方：Project References — https://www.typescriptlang.org/docs/handbook/project-references.html
• tsconfig options — https://www.typescriptlang.org/tsconfig
• Nx monorepo guide — https://nx.dev
• baseUrl — https://www.typescriptlang.org/tsconfig/baseUrl.html
• paths — https://www.typescriptlang.org/tsconfig/paths.html
• TypeScript 6.0 Release Notes — https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html

学习检查

不看正文回答：

1. tsconfig.json 最核心的职责为什么不只是“存编译器参数”，而是定义一个 TypeScript program 如何被理解和构建？
2. include/exclude、rootDir/outDir、strict、module/moduleResolution 分别控制哪一类边界？
3. 为什么前端 bundler 项目与直接交给 Node 运行的项目会选择不同的模块解析策略？
4. Monorepo 中为什么会出现 composite、references 和声明产物这些额外需求？
5. paths 为什么不能简单理解成“运行时自动支持的路径别名”？
6. 给一个新的 TypeScript 项目，你会先确认哪些环境条件，再决定 tsconfig？

掌握验收

• 能从 program 边界、类型检查、模块解析、emit、项目引用五个维度读懂一个陌生 tsconfig；
• 能解释关键选项为什么存在，而不只是背默认值；
• 遇到模块解析或 monorepo 问题时，能跳转到对应原子笔记定位问题。