真正能把 TypeScript 配置与工程化讲清楚的内容并不多。这章看起来最简单无非是一个 tsconfig.json加上几个脚本命令但实际它决定了一个项目在后续一年里的编译速度、类型可靠程度、跨模块协作方式。很多项目初期跑得飞快等到几千个文件、多人并行开发、依赖一多才开始暴露出配置层面的问题。所以这一篇就把 TypeScript 配置与工程化放在一起讲适合正在维护中型以上项目、或者准备给团队定一套 TypeScript 规范的人参考。1. 先把 tsconfig 当成一份工程契约而不是“能编译就行”的开关1.1 target、module、lib 三个字段看着像同一个概念其实是三套系统很多初学者容易把 target、module、lib 混为一谈觉得它们都是“决定代码最终长什么样”的选项。实际上它们分别管三件不同的事target 决定语法要降级到什么版本比如把新语法转成 ES2017 还是 ES2020module 决定产物里的模块系统是 CommonJS 风格还是 ES Module 风格lib 决定类型检查器默认能识别的内置 API 类型比如 Set、Promise、Array.at 这些方法是否存在。它们三者的联动关系比大多数人想象的要复杂。target 改了生成代码里的 async/await 或者可选链可能被转换lib 如果没跟上代码里调用的某些新 API 就会被判定为“类型不存在”。反过来说lib 里声明了很多 API但 target 太低转译器也不会凭空给你补 polyfill最后只是“类型上允许、运行时未必支持”。我见过一个很典型的场景有人在代码里用了数组的.at()方法本地 TypeScript 版本没报错因为编辑器恰好加载了更完整的 lib但 CI 环境里的 tsconfig 把 target 定在 ES2019又没有显式配置 lib结果类型检查直接失败。这类问题不看配置很难定位因为你代码本身没问题问题是“配置里声明的能力边界”跟不上代码。这里我的建议是把 target、module、lib 当成三套独立的决策来做。target 看你的运行环境要求lib 看你要用哪些新 API 类型module 看你的产物给谁消费。不要把 ES2022 这种值同时填进三个字段就以为万事大吉。一个相对稳的配置长这样{ compilerOptions: { target: ES2020, module: Node16, lib: [ES2021, DOM] } }这只是一个示例。真实项目里浏览器端和 Node 端的 lib 取舍完全不同。但核心原则是一致的显式写出 lib不要隐式依赖 target 自动附带的那套。1.2 strict 的代价很大但多数项目应该在第一天就把它打开strict 不是一个单选项它更像是一整组规则的汇总包括 noImplicitAny、strictNullChecks、strictFunctionTypes、strictPropertyInitialization、strictBindCallApply 等若干条。打开 strict 的代价很明显代码里所有隐式 any、可能的空值、未初始化属性都会被查出来对于没接触过严格类型的开发者来说第一天可能就会收到几十个报错。但代价换回来的收益更明显。举一个最简单的例子function prefix(name: string | null) { return user: name; }如果没开 strictNullChecks这段代码编译不会报错运行结果却可能变成user:null。开了 strict 以后你会被逼着先处理空值function prefix(name: string | null) { return user: (name ?? unknown); }这种“逼着”在工程化里非常重要。因为类型系统的价值不是在你写代码这一刻体现而是在三个月后、别人接手时、或你自己在调试某个诡异线上问题时体现。打开 strict 的项目很多问题在编译阶段就被拦下来了运行阶段反而清爽很多。老项目如果一开始没开 strict不要试图一天晚上把它全部打开那只会让团队产生对抗情绪。更现实的做法是新项目从一开始就开老项目按目录分批开放每次开放只处理一批文件同时把“未开放 strict 的目录”记录成技术债清单。最怕的是永远不开因为每拖延一天新增代码都在继续制造新的隐式 any后面的迁移成本只会越来越高。1.3 include 和 exclude 只能缩小入口挡不住“被 import 进范围内的文件”tsconfig 里的 include 和 exclude 看起来很容易理解但常见误区很多。include 是一个入口白名单exclude 是从白名单里剔除某些路径。可很多开发者把 exclude 当成“万能屏蔽”想把某些有问题的第三方目录排除掉却发现根本不起作用。原因在于TypeScript 做类型检查时不只看入口文件还会沿着所有 import 关系把依赖文件拉进类型推导过程。如果某个问题文件在你的 src 里被 import 了即使它不在 include 范围内也可能因为类型依赖链条而参与检查。另一个常见坑是“把构建产物也放进检查路径”。有些项目在根目录 include 写得很宽比如[src, dist]结果上一轮构建生成的.d.ts或.js文件下一轮又把它们当输入文件重新检查既慢又容易产生迷惑性报错。正确做法是让 include 只精确指向源码目录{ include: [src], exclude: [node_modules, dist, coverage] }严格来说exclude 里的 node_modules 在多数情况下是多余的因为默认就会排除它。但写出来有一个好处让读配置的人明确知道“哪些目录是被有意排除的”。真正需要避免的是靠 exclude 去解决“某个第三方包类型有问题”这种场景——那种问题应该靠类型声明或模块解析配置解决而不是在入口处把它藏起来。2. 提速第一步把类型检查和代码转译拆成两条赛道2.1 类型检查为什么往往成为团队协作里的第一块减速带很多项目的构建流程是把“类型检查”和“把 TS 代码转成 JS”绑在一起做的。项目小的时候无所谓等到文件上千你会明显感觉到每次按保存编辑器要重新检查整个依赖图每次跑构建又要把整套类型检查从头过一遍。原因在于类型检查本质上需要追踪类型流向。简单说它要做“类型推导”和“类型验证”这比单纯的“语法去掉”要重得多。转译只需要处理单个文件或少量文件类型检查却必须沿着 import 图把关联的类型全走一遍。工程化里最值得做的第一件事就是把这两件事拆开。比如用tsc --noEmit做类型检查它只负责验证不输出 JS 文件而在开发调试或构建阶段用另一套只做语法转换的流程把 TS 语法剥掉、输出 JS。转译不查类型所以速度会快很多类型检查就放到提交前、CI 门禁里去做。这里的核心思路是保留“类型检查必须存在”的底线但不要让它成为每次保存、每次热更新都要付出的代价。打个比方快递员打包发货时不需要每次都复核整个仓库的商品账目账目复核应该放在日常盘点或出货前质检环节。2.2 保存、提交、发布三个阶段检查密度应该不一样不同类型的代码变动需要不同的检查深度。我的习惯是把检查分为三层保存阶段只做快速转译让开发调试尽快看到效果。这里的报错尽可能聚焦在当前文件不要让全项目的存量错误干扰新代码调试。提交阶段做增量类型检查和静态检查。只检查本次变更涉及的文件及相关依赖保证提交进去的代码是基本健康的。发布/合并阶段做一次全量类型检查。因为增量检查可能漏掉跨文件相互影响的问题全量检查才有最终说服力。对应的 package.json scripts 大致是这样{ scripts: { typecheck: tsc --noEmit, typecheck:ci: tsc --noEmit --force } }这里的--force只是示意意思是 CI 环境里不要信任本地增量缓存。如果你用的是自身支持增量模式的编译流程本地可以在 tsconfig 里开incremental: true生成.tsbuildinfo缓存文件但要注意这个缓存文件必须在版本管理里被忽略同时 CI 环境最好不要复用它否则容易出现在 CI 上“怎么都报不出错”、本地却一堆错的反常情况。三层检查密度的设计本质上是在“反馈速度”和“检查可靠性”之间找平衡。开发者最反感的是每次保存都卡三秒但只要在提交和合并阶段严格把关项目质量并不会因此失控。2.3 sourceMap、declaration 和 outDir 是给协作双方看的配置如果你只写业务代码sourceMap 可能只是“断点调试能用”的印象但如果你是写公共库或者多包仓库sourceMap、declaration 和 outDir 这三项配置直接决定了下游使用者能不能顺畅地定位问题。先看 declaration。它控制是否生成.d.ts声明文件。库源码经过转译后JS 文件里的类型信息基本都丢掉了如果不下发声明文件下游消费方完全拿不到提示只能看到一堆any。所以凡是需要对外发布的包declaration 几乎都必须开。再看 declarationMap。它会把.d.ts文件里的位置映射回源.ts文件。有了它下游开发者在 IDE 里跳转到某个声明时可以直接回到你的源码而不是停在一个抽象的类型签名上。这个对开源库和公司内部公共包体验提升非常明显但很多人会忽略。outDir 则是决定产物输出目录的。这里有一个容易被忽略的细节产物目录最好不要和源码目录嵌套比如 src 输出到 dist就不要让 dist 出现在 src 的 include 范围内。否则下次全量检查时旧产物文件可能会被当成源文件重复检查既拖慢速度又污染报错信息。这三个配置看着简单但它们的组合使用方式往往能看出一个团队是把 TS 当成“能跑就行”的工具还是当成一套给上下游协作的工程规范。3. 路径别名与多包仓库模块解析里真正的三个暗坑3.1 paths 只改了 TypeScript 的“视线”运行时未必跟得上路径别名是大多数项目都会用到的东西。为了避免写../../../utils/format这种深层相对路径很多人会在 tsconfig 里配置{ baseUrl: ., paths: { core/*: [src/core/*] } }配置之后代码里写import { format } from core/formatTypeScript 编译阶段确实能找到文件类型检查也能通过。但问题常常出现在运行阶段你转译出来的 JS 产物里模块路径仍然可能是core/format而运行时模块解析环境根本不知道core对应哪个目录于是一执行就报“模块找不到”。这个坑要注意的关键点是tsconfig 里的 paths 只是告诉你 TypeScript “允许这么写”并没有告诉打包器、运行时、或 Node 的模块解析器也这么做。因此只要项目里用了路径别名就必须保证构建链里同步对齐这套映射方案。常见的做法是在打包配置里也配置对应的别名或者通过 package.json 里的 imports 字段做一套统一映射而不是让 tsconfig 成为唯一的信息源。给一个可落地的检查清单确认转译后的产物里路径别名是否被替换成真实相对路径确认构建工具配置里的别名和 tsconfig 里完全一致确认运行时如果直接加载产物是否还需要额外的模块映射配置确认新增目录时不会因为路径别名映射范围不够导致编译通过却运行失败。大部分“编译通过了、运行就崩”的问题都出在这一层。3.2 多包场景里的项目引用先解决声明文件的产出顺序在 monorepo 或者多包仓库里一个包经常依赖另一个包。此时容易遇到两种情况直接引用另一个包的源码目录或者引用另一个包发布后的产物和声明文件。引用源码目录的优点是调试方便、不需要先构建依赖方缺点是每个包都要互相认识对方的源码结构类型检查的跨包路径也容易变得越来越复杂。引用产物和声明文件则更接近最终运行状态但要求被依赖的包必须先完成构建至少要先生成声明文件否则下游包的 TypeScript 只能在产物里看到一个“空壳”。TypeScript 提供了一种工程级方案项目引用。通过reference配置一个项目可以明确声明自己依赖了哪些子项目并让构建器按依赖顺序自动处理构建。使用项目引用的前提是每个被引用项目都开启composite: true同时把declaration: true打开因为项目引用本质上依赖声明文件来传递类型信息。这套方案真正能帮上忙的场景是大型仓库里需要反复跨包构建、并且依赖关系稳定明确的情况。但如果你的包之间存在循环依赖项目引用也救不了你。工程化解决不了架构问题循环依赖应该先在代码层消除而不是靠配置去硬扛。3.3 编译报错和运行报错要分开查别只盯 import 拼写接到“模块找不到”类型的报错第一反应不应该是反复检查 import 拼写而是先判断报错发生在“编译阶段”还是“运行阶段”。如果是编译阶段报错比如Cannot find module出现在你用 tsc 做类型检查的时候问题大多数出在 tsconfig 的模块解析配置上。可能是 moduleResolution 和 module 不匹配可能是 paths 没配全也可能是某个包没有类型入口。这类问题改配置就能解决代码本身可能没问题。如果是运行阶段报错比如转译后的 JS 在执行时报找不到模块那就是产物实际加载路径的问题。这时候要去看产物文件结构转译后文件到底在哪一层目录模块写法是 CommonJS 的 require 还是 ESM 的 import路径别名在产物里是否还被保留。两套排查思路完全不同混在一起查效率会非常低。我一般会做一个简单表格来判断报错现象优先怀疑层处理位置编译阶段无法解析模块tsconfig 模块解析配置对齐编译通过、运行报模块找不到转译/打包产物构建链路配置包有产物但没有类型提示声明文件缺失补类型声明4. 把团队规范焊死在配置里格式化、静态检查与提交门禁4.1 类型检查、静态检查、格式化三件事职责别搞混工程化到了团队协作阶段光靠 tsconfig 是不够的还要搭配静态检查、格式化和测试这些手段。但很多团队会把它们的职责混在一起导致配置文件越看越复杂问题却越查越乱。TypeScript 的主要职责是类型安全能不能赋值、参数对不对、有没有隐式 any。静态检查工具的主要职责是代码卫生有没有未使用变量、有没有危险写法、命名是否符合规范。格式化的职责就更单纯缩进、引号、逗号风格统一排版。三件事互相有交集但不要互相替代。典型的反面做法是在 tsconfig 里把 noUnusedLocals 关了理由是“静态检查工具已经能查未使用变量”同时又在静态检查工具里把某个没用的规则关掉理由是“TS 配置已经管过了”。结果两边都觉得对方在管实际上都没管。规则归属最好清晰统一能交给 TS 的类型规则就交给 TS代码风格和潜在逻辑问题交给静态检查排版统一交给格式化工具。团队里还要尽量做到“配置共享”。把 tsconfig、静态检查配置、格式化配置提升到项目共享层而不是每个项目各写一份。多个项目各写一份半年后一定会出现 A 项目开了严格检查、B 项目还能随便 any 的割裂现象。4.2 提交前的四道门禁顺序比数量更重要我推荐团队在提交代码前设置四个阶段的门禁顺序很重要格式化先统一排版避免后续 diff 里混入大量无关格式变更静态检查检查当前变更文件的代码风格和潜在隐患类型检查对变更相关范围做类型验证针对性测试跑和本次变更相关的测试集不是全量测试。顺序之所以重要是因为每一步失败的成本不一样。格式化失败最快修复测试失败成本最高。如果一上来先跑全量测试很可能连格式化还不统一的代码也被拉进测试产生一堆无效失败。提交钩子里的脚本大致长这样format --check lint tsc --noEmit test --related这里要特别提醒一点本地钩子里的检查可以被开发者的本地环境差异影响。比如某台机器装了不同版本的依赖、缓存没有清理、或者配置被跳过。所以本地检查只能作为第一道防线真正有公信力的检查必须放在 CI 门禁里。CI 环境干净、可重复、不信任本地缓存跑出来的结果才是团队可以依赖的“标准答案”。4.3 门禁失败的信息决定了开发者是修问题还是绕过问题配置门禁容易让开发者愿意配合门禁很难。我观察到一个规律门禁失败信息写得越模糊开发者越倾向于绕过门禁。要么直接--force提交要么在配置里把某条规则临时注释掉然后“忘了”恢复。失败的提示至少要包含三样信息执行的是哪条命令报错的具体文件和规则位置修复方向或去哪个配置文件里看更多说明。比如类型检查失败时只输出Found 3 errors是不够的。更好的做法是让命令输出具体到文件、行列和错误类型并且在钩子提示里写清楚“如果你需要临时跳过检查请先确认不会合入主干并在提交说明里注明原因”。门禁的意义不在于制造障碍而在于让每次提交都有可追溯的质量记录。一个写得好的门禁提示本质上是一段面向开发者的即时辅导比事后 review 的体验好得多。5. 最后一公里类型声明缺失、孤立模块与配置漂移5.1 第三方依赖没有类型时声明文件要补但也别补到失控工程化最常见的临门一脚问题是某个依赖没有官方类型声明或者声明写得很烂。很多人第一时间想到的是把模块声明成 any比如建一个全局声明文件里面写declare module *结果整个项目的类型推断都被带崩了。正确做法是给特定模块补一份最小声明。只声明确实用到的导出不要试图完整还原整个模块的类型。比如declare module legacy-util { export function calc(input: string): number; export const version: string; }这里用的是虚构模块名实际项目里替换成你依赖的真实模块名。声明文件放在项目的 types 目录下并在 tsconfig 里确认 typeRoots 或 include 能覆盖到它。还有一个容易被忽略的点手动补的声明要纳入版本管理并且在 readme 或注释里记录为什么补、补到哪个版本、依赖方升级后是否需要重新评估。否则三个月后维护者已经说不清这个声明文件是“官方给的”还是“自己编的”一升级依赖破绽全出来了。5.2 孤立转译模式下的配置项往往才是跨环境报错的来源有些构建链路在转译 TS 时会把每个文件当成独立单元处理不像 tsc 那样基于全项目类型信息工作。这种模式速度很快但对代码书写有一定的约束。比如你依赖了某个类型并用export { SomeType }这种写法把它导出在孤立转译模式下它可能因为无法判断这是类型还是值导致产物里留下一个不该存在的导入或反过来把该保留的导入删掉。隔离文件模式下的典型配置项就是 isolatedModules。开启后TypeScript 会提前暴露那些“在单文件视角下不合法”的写法比如某些 const enum 的写法只含类型的再导出需要跨文件推导才能决定保留或删除的导入。新项目直接把这些配置打开是比较稳妥的因为现在越来越多人用按文件转译的方式进行构建。老项目如果长期依赖 tsc 的全量类型检查做转译迁移到新型构建链路时要格外注意这类问题。报错不一定在项目里立刻出现往往要等到产物真正跑起来、某个类型残留成运行时导入时才暴露。5.3 TypeScript 版本升级带来的默认值变化要用显式配置来对抗漂移最后一个工程化里的隐藏问题是 TypeScript 版本升级带来的“默认值漂移”。很多 tsconfig 配置只写了自己关心的字段其他大量选项都依赖当前版本的默认值。于是在某个大版本升级之后团队突然发现 CI 出现几百个新报错明明自己一行代码都没改。这不是代码变烂了而是检查规则变严了。面对这种情况不要第一反应去关规则。正确步骤是先区分“新代码触发的错误”和“历史代码被新规则覆盖产生的错误”。新代码的错误尽快修复历史代码的错误可以单独列出来分批处理而不是一刀切降级配置。我自己的做法是在 tsconfig 里显式写出所有对项目行为有决定意义的字段不依赖默认值。这样升级后哪些行为是项目自己设定的、哪些是跟随版本变化的一眼就能看清。同时每一次 TypeScript 升级都要在 CI 里做一次全量类型检查并且在一个独立的合并请求里完成升级而不是混在业务改动里顺手带上去。配置漂移的控制说到底是“可追踪性”的问题。你不需要阻止工具版本前进但你必须让每一次前进的后果都是可见的、可回滚的。最后说一个我自己的习惯每次接手一个 TypeScript 项目我会先花半小时把 tsconfig 从头到尾读一遍而不是急着翻业务代码。因为配置里藏着这个项目团队对类型安全的真实态度。配置写得很随意代码再漂亮也维持不了多久。如果你现在正被某条“编译过了但运行就崩”的问题困住优先去看 module、paths、declaration 这三个位置很多时候问题不在你的代码而在你把代码交给谁去编译、用什么配置去编译。