1. 为什么 tsconfig.json 值得你花时间吃透如果你写过一段时间 TypeScript大概率经历过这样的场景项目跑得好好的某天加了个新目录编辑器突然满屏红波浪线或者本地tsc编译一切正常CI 上却报了一堆类型错误再或者import路径写起来像迷宫../../../数到眼花。这些问题十有八九都指向同一个地方——tsconfig.json。tsconfig.json是 TypeScript 项目的“总控台”。它决定了哪些文件参与编译、编译成什么目标、模块怎么解析、类型检查有多严格、路径别名怎么配、增量构建缓存放哪。很多人对这个文件的态度是“脚手架生成啥就用啥”能跑就不动。但一旦项目规模上来或者要接入构建工具、要发布 npm 包、要做 monorepo这个文件里每一个选项都会变成你必须理解的东西。这篇文章面向所有正在用 TypeScript 的人——不管你是刚接触tsc的新手还是已经能背出strict系列选项的老手。我会把tsconfig.json从整体结构到核心字段逐个拆开讲清楚解释每个选项背后的设计意图给出可以直接抄的配置模板再分享一些我在实际项目里踩过的坑。读完你至少能做到看到任何一个tsconfig.json都能读懂它在干什么并且能根据自己的项目需求改出合适的配置。需要先说明一点TypeScript 版本迭代很快部分选项在不同版本间有弃用和迁移。比如baseUrl在较新版本中已经被标记为弃用官方建议用paths配合其他方式替代moduleResolution: node10同样进入了弃用通道。这些变化我会在对应章节里点出来避免你照着老教程配完发现一堆警告。2. tsconfig.json 的整体结构与加载逻辑2.1 这个文件到底长什么样从结构上看tsconfig.json就是一个 JSON 文件根层级只有几个顶层字段最核心的是compilerOptions其余是描述“编译哪些文件”的字段。一个最小可用的配置大概是这样{ compilerOptions: { target: ES2020, module: ESNext, strict: true }, include: [src/**/*] }顶层字段主要有这几个compilerOptions编译器选项99% 的配置都写在这里。include指定要纳入编译的文件 glob 模式。exclude排除哪些文件默认会排除node_modules、bower_components、jspm_packages和outDir。files精确列出要编译的文件适合文件极少的场景一般不用。extends继承另一个配置文件monorepo 和分层配置的基石。references项目引用用于把大项目拆成多个可独立编译的子项目。compileOnSave老编辑器时代的产物现在基本被语言服务取代可以忽略。理解这几个字段的优先级很重要。files的优先级最高它列出的文件一定会被编译include和exclude是一对include决定候选集合exclude从中剔除如果两者都没写默认编译当前目录及子目录下所有.ts、.tsx、.d.ts文件。这里有个容易踩的坑exclude只对include生效如果你用files显式列了某个文件即使它在exclude里也照样会被编译。2.2 配置是怎么被找到和合并的当你运行tsc而不指定文件时编译器会从当前目录开始向上逐级查找tsconfig.json找到第一个就用它。你也可以用tsc -p ./some/path/tsconfig.build.json显式指定。这个“向上查找”的行为在多包仓库里特别容易出问题——子目录里跑tsc可能意外用了根目录的配置。extends的合并规则值得单独说。它做的是“浅合并”加“覆盖”子配置里出现的字段会整体覆盖父配置的同名字段而不是深度合并。举个例子父配置compilerOptions.paths里有两个别名子配置只写了一个那结果就是子配置那一个父配置的两个不会保留。这一点和很多人直觉里的“合并”不一样我见过有人因此丢了路径别名排查半天。extends的路径解析也有讲究。如果写的是相对路径相对于当前配置文件所在目录解析如果写的是包名比如tsconfig/node20/tsconfig.json则按 Node 模块解析规则去找。社区里有一批官方维护的基础配置包直接继承能省不少事。2.3 为什么建议把配置分层在中大型项目里我强烈建议把配置拆成至少两层一个tsconfig.base.json放通用规则一个tsconfig.json放项目特定规则。这样做的好处是当你有多个子项目比如前端、后端、测试时公共部分只维护一份改一处全生效。更进一步构建产物和类型检查其实可以用不同的配置。类型检查要覆盖测试文件、要开最严格的检查构建产物只需要源码、要生成声明文件、要去掉测试。用tsconfig.json做类型检查、tsconfig.build.json做构建是很多库项目的标准做法。tsconfig.build.json里通常写extends: ./tsconfig.json然后exclude: [**/*.test.ts, **/*.spec.ts]。3. compilerOptions 核心选项逐个拆解3.1 target、lib 与 module决定输出形态的三兄弟target决定编译后代码的语法版本可选值从ES3一直到ESNext。它影响的是语法降级比如你写async/awaittarget是ES5时会被编译成__awaiter辅助函数target是ES2017及以上则原样保留。选target的原则很简单看你的运行环境支持到哪。现代 Node 和现代浏览器基本都支持ES2020以上没必要为了兼容远古环境把代码降级得面目全非。lib决定编译时能用的内置类型声明比如DOM、ES2020、WebWorker。它和target是解耦的target管语法lib管类型。一个常见误区是只改target不改lib结果想用Promise.allSettled却提示不存在。稳妥的做法是让lib至少包含target对应的 ES 版本比如target: ES2020就配lib: [ES2020, DOM]。如果是纯 Node 项目把DOM去掉避免误用浏览器 API 却编译通过。module决定输出什么模块格式可选CommonJS、ESNext、NodeNext、Preserve等。这里有个关键点module和moduleResolution是配套的。用NodeNext时moduleResolution也应该是NodeNext它会根据package.json的type字段和文件扩展名来决定模块解析方式。如果你在写 ESM 的 Node 项目module: NodeNext基本是唯一正确选择。3.2 strict 家族类型安全的开关组strict: true不是一个选项而是一组选项的总开关。打开它等于同时打开了下面这一串选项作用典型影响noImplicitAny禁止隐式 any未标注类型的参数会报错strictNullChecksnull/undefined 独立类型必须显式处理可能为空的值strictFunctionTypes函数参数逆变检查回调类型不兼容会报错strictBindCallApply校验 bind/call/apply参数类型不匹配会报错strictPropertyInitialization类属性必须初始化构造函数里没赋值会报错noImplicitThis禁止隐式 thisthis 类型不明确会报错alwaysStrict输出严格模式每个文件加 use strictuseUnknownInCatchVariablescatch 变量为 unknowncatch 里不能直接当 any 用新项目我建议无脑开strict。老项目迁移时如果一次性开报错太多可以逐个打开先开strictNullChecks和noImplicitAny这两个收益最大的。strictNullChecks尤其重要它逼着你处理空值能消灭大量运行时的Cannot read property of undefined。除了strict家族还有几个强烈建议开的检查noUnusedLocals和noUnusedParameters能揪出没用的变量和参数noFallthroughCasesInSwitch防止 switch 漏写 breaknoImplicitReturns要求所有分支都有返回值。这些在团队协作里能省下大量 review 时间。3.3 moduleResolution 与 paths模块解析的规则与捷径moduleResolution决定 TypeScript 怎么找到import的模块。历史上主要有两种node10旧称node和node16/nodenext。node10模拟的是老式 Node 的解析行为不区分 ESM 和 CJS也不强制文件扩展名。node16/nodenext则严格遵循现代 Node 的 ESM 规则要求相对导入带扩展名。这里要特别提醒moduleResolution: node10已经被标记为弃用官方计划在 TypeScript 7.0 中移除。如果你现在还在用它建议尽早迁移到bundler或nodenext。bundler是给打包工具Vite、webpack、esbuild用的它允许省略扩展名行为和打包工具一致是目前前端项目的主流选择。paths是路径别名配合baseUrl使用注意baseUrl在新版本中已弃用现在paths可以独立于baseUrl工作路径相对于配置文件所在目录解析。一个典型配置{ compilerOptions: { paths: { /*: [./src/*], utils/*: [./src/utils/*] } } }配了paths之后tsc能正确解析类型但运行时不一定认识这些别名。这是新手最容易踩的坑编辑器不报错一跑就Cannot find module。原因是paths只影响类型检查不影响运行时模块解析。解决办法是让运行时也认识别名——用打包工具的话在打包配置里配同样的 alias纯 Node 环境可以用tsc-alias这类工具在编译后重写路径或者干脆用 Node 的imports字段。3.4 输出相关outDir、rootDir 与 declarationoutDir指定编译产物输出目录rootDir指定源码根目录。这两个要配合好否则输出目录结构会乱。规则是outDir里的目录结构由rootDir到各源文件的相对路径决定。如果不设rootDirTypeScript 会取所有输入文件的公共父目录作为根这可能导致输出结构和你预期不一致。举个例子源码在src/下测试在test/下如果两个都参与编译且不设rootDir公共父目录是项目根输出就会变成dist/src/...和dist/test/...。设了rootDir: ./src之后输出就是干净的dist/...。所以构建配置里通常会把测试排除掉并显式设rootDir。declaration: true生成.d.ts类型声明文件发布 npm 包必须开。declarationMap: true生成声明文件的 source map方便使用者跳转到源码。sourceMap: true生成 JS 的 source map调试用。removeComments去掉注释noEmit只做类型检查不输出文件——后者在“用打包工具构建、只用 tsc 检查类型”的项目里非常常用。3.5 增量与性能incremental、skipLibCheck 与 isolatedModulesincremental: true开启增量编译TypeScript 会把上次编译的信息存到.tsbuildinfo文件里下次只重新编译变化的部分。大项目里这个开关能显著缩短编译时间。配合tsBuildInfoFile可以指定缓存文件位置建议把它放进outDir或专门的缓存目录别污染项目根目录。skipLibCheck: true跳过对.d.ts文件的类型检查。这个选项争议很大但我的实践是绝大多数项目都该开。原因是第三方库的声明文件质量参差不齐检查它们经常报出你根本改不了的错误白白浪费时间。跳过库检查不影响你自己代码的类型安全。isolatedModules: true要求每个文件都能被独立编译这对 Babel、esbuild、SWC 这类逐文件转译的工具很重要。开了它之后const enum和某些类型的重新导出会受限。用现代打包工具的项目建议开启能提前发现那些“tsc 能过但打包工具处理不了”的写法。4. 不同场景下的配置模板与实操4.1 现代前端项目Vite React前端项目现在基本是 Vite 的天下配置上要照顾到打包工具的行为。下面这份是我常用的模板{ compilerOptions: { target: ES2020, lib: [ES2020, DOM, DOM.Iterable], module: ESNext, moduleResolution: bundler, jsx: react-jsx, strict: true, noUnusedLocals: true, noUnusedParameters: true, noFallthroughCasesInSwitch: true, isolatedModules: true, skipLibCheck: true, noEmit: true, resolveJsonModule: true, allowImportingTsExtensions: true, paths: { /*: [./src/*] } }, include: [src] }几个关键点解释一下。moduleResolution: bundler让类型解析和 Vite 保持一致允许省略扩展名。noEmit: true是因为构建交给 Vitetsc只负责类型检查通常配合tsc --noEmit作为 CI 的一步。allowImportingTsExtensions允许在 import 里写.ts/.tsx扩展名这个选项要求noEmit或emitDeclarationOnly同时开启。jsx: react-jsx是 React 17 之后的新 JSX 转换不需要再手动import React。resolveJsonModule让你能直接import data from ./data.jsonVite 和 webpack 都支持配上类型解析才不报错。DOM.Iterable补上NodeList、HTMLCollection等的迭代器类型遍历 DOM 集合时很有用。4.2 Node 后端项目ESMNode 项目现在越来越多用 ESM配置和前端差别不小{ compilerOptions: { target: ES2022, lib: [ES2022], module: NodeNext, moduleResolution: NodeNext, strict: true, outDir: ./dist, rootDir: ./src, declaration: true, sourceMap: true, incremental: true, tsBuildInfoFile: ./dist/.tsbuildinfo, skipLibCheck: true, esModuleInterop: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules, dist, **/*.test.ts] }module: NodeNext要求相对导入必须带.js扩展名即使源文件是.ts这是 ESM 的硬性规则很多人第一次遇到会懵。esModuleInterop: true让import fs from fs这种默认导入能正常工作不开的话得写import * as fs from fs。forceConsistentCasingInFileNames强制文件名大小写一致能避免在大小写不敏感的系统macOS、Windows上开发、在 Linux 上构建时出现的诡异问题。tsBuildInfoFile我特意放进了dist这样清理构建产物时缓存也一起清掉不会出现“删了 dist 但缓存还在导致编译结果不对”的情况。4.3 库项目要发布 npm 包发布 npm 包对配置要求最高因为你要同时产出 JS、类型声明还要考虑使用者的各种环境{ compilerOptions: { target: ES2020, module: ESNext, moduleResolution: bundler, strict: true, declaration: true, declarationMap: true, sourceMap: true, outDir: ./dist, rootDir: ./src, skipLibCheck: true, isolatedModules: true, verbatimModuleSyntax: true }, include: [src], exclude: [**/*.test.ts, **/*.spec.ts] }verbatimModuleSyntax: true是个比较新的选项它要求类型导入必须用import type显式标注普通import不会被擦除。这样做的好处是编译结果更可预测配合打包工具时不会出现“以为擦掉了结果留下了”的问题。declarationMap让使用者在编辑器里点进你的类型能跳到源码体验好很多。库项目通常还要产出多种模块格式CJS ESM这靠tsc单次编译做不到一般用打包工具或者跑两次tsc配不同module。如果跑两次记得第二次的outDir和tsBuildInfoFile要区分开否则缓存会互相覆盖。4.4 monorepo 与项目引用monorepo 里references是核心。假设你有packages/core和packages/appapp依赖core{ compilerOptions: { composite: true, declaration: true, outDir: ./dist, rootDir: ./src }, include: [src], references: [{ path: ../core }] }composite: true是项目引用的前提它强制开启declaration并要求所有源文件都在include范围内。被引用的项目必须先构建tsc -b命令会按依赖顺序自动构建整个引用图。tsc -b --watch则能监听所有项目的变化增量重建monorepo 开发体验靠它。项目引用最大的价值是增量构建和边界清晰。每个包独立编译改一个包只重建它和依赖它的包不用全量编译。同时它强制包之间只能通过公开入口互相引用避免了跨包直接 import 内部文件的混乱。5. 常见问题与排查技巧实录5.1 编辑器不报错但编译报错或反过来这是最高频的问题根源通常是编辑器用的 TypeScript 版本和项目里的不一致。VS Code 默认用自带的 TS 版本可能和你node_modules里的差好几个大版本。解决办法是在 VS Code 里执行 “TypeScript: Select TypeScript Version”选 “Use Workspace Version”。团队里最好在.vscode/settings.json里固定这个设置避免每个人环境不同。另一个原因是编辑器读的配置和tsc读的不是同一个。比如你在子目录里跑tsc它向上找到了根目录的配置而编辑器用的是子目录的配置。排查方法是在报错文件所在目录跑tsc --showConfig看看实际生效的配置是什么。5.2 路径别名运行时找不到模块前面提过paths只管类型不管运行时。排查时先确认三件事打包工具或运行时的 alias 配了没、paths的路径基准对不对、有没有baseUrl的历史遗留问题。baseUrl弃用后paths的值相对于配置文件所在目录解析如果你从老项目迁移过来原来依赖baseUrl的相对路径可能要调整。一个实用的调试技巧是用tsc --traceResolution打印模块解析的完整过程它会告诉你 TypeScript 尝试了哪些路径、为什么没找到。输出很长但配合 grep 过滤目标模块名定位问题非常快。5.3 编译产物目录结构不对症状是dist里多了一层src或者文件散落在意料之外的位置。根因基本都是rootDir没设或设错。记住那条规则输出结构 源文件相对rootDir的路径。如果没设rootDirTypeScript 取所有输入文件的公共父目录。所以当你发现多了一层先检查是不是有include范围外的文件被拉进来了把rootDir显式设成源码目录通常能解决。还有一种情况是include用了过于宽泛的 glob把配置文件、脚本文件也纳入了编译。建议include精确到源码目录其他文件用exclude兜底。5.4 增量编译缓存导致的诡异问题incremental用久了偶尔会遇到“明明改了代码但编译结果没变”或者“删了文件还报旧错误”。这通常是.tsbuildinfo缓存和实际文件状态不一致。最直接的解法是删掉.tsbuildinfo重新全量编译。为了减少这类问题把缓存文件放进outDir并在清理脚本里连同dist一起删。另外tsc -b在 monorepo 里如果某个包的tsbuildinfo损坏可能导致整个构建图卡住。遇到构建行为异常时先试tsc -b --force强制全量重建能排除大部分缓存问题。5.5 常见问题速查表症状可能原因排查动作编辑器与命令行结果不一致TS 版本不同 / 配置不同固定工作区 TS 版本tsc --showConfig别名运行时找不到运行时未配 alias检查打包配置或用tsc-alias输出多一层目录rootDir未设或设错显式设rootDir为源码目录编译结果不更新增量缓存不一致删除.tsbuildinfotsc -b --force第三方库类型报错库声明文件质量问题开skipLibCheckESM 导入报扩展名错误moduleResolution为 NodeNext相对导入补.js扩展名baseUrl弃用警告用了旧配置移除baseUrlpaths独立使用6. 我踩过的坑和几条实用建议先说一个我印象最深的坑。有次接手一个项目tsconfig.json里include写的是[**/*]exclude只排了node_modules。结果dist目录里的旧编译产物被当成源码又编译了一遍输出嵌套了好几层构建越来越慢。排查了半天才反应过来是include太宽。从那以后我养成了习惯include永远精确到源码目录exclude永远把dist、coverage、build这些产物目录列全。第二个坑是关于strict的。有个老项目一直没开strictNullChecks某次升级依赖后类型定义变了一堆地方开始报错。当时想一次性开strict全修结果几百个错误根本改不完。后来改成按目录逐步开先在新代码目录开严格模式老代码用单独的配置放宽慢慢迁移。这个过程教会我类型严格度是可以渐进提升的别指望一步到位。第三个是关于extends的浅合并。我在一个 monorepo 里让子包继承根配置根配置里配了paths子包想加一个自己的别名就只写了自己的那个。结果根配置的别名全丢了编辑器一片红。查了文档才确认extends是整体覆盖而非深度合并。解决办法是要么在子配置里把父配置的paths完整重写一遍要么把公共别名抽到一个单独的基础配置里两边都继承它。几条实用建议收尾。第一把tsc --noEmit加进 CI 的必过步骤类型检查不该只靠编辑器。第二定期跑tsc --showConfig看看实际生效的配置尤其是用了extends之后确认合并结果符合预期。第三关注 TypeScript 的弃用警告baseUrl、moduleResolution: node10这些都在迁移窗口期早改早省心。第四配置里多写注释——tsconfig.json支持 JSONC允许注释把每个非默认选项的原因写清楚半年后的你会感谢现在的自己。
