TypeScript 项目编译慢？5分钟优化指南

TypeScript 项目编译慢5 分钟搞定性能优化如果你维护过中型以上的 TypeScript 项目肯定遇到过这种场景改一行代码webpack 或 vite 的转编译没崩但プロセス卡了几秒甚至几十秒然后终端里滚出一大片类型错误日志。要是再碰上团队里有人用 dev server 热更新几乎每次保存都要瞪着菊花转半天。这种事几乎没人会写进文档但遇到过一次就会留下阴影。更气的是很多项目并没有用 TSC 做什么严格的类型检查纯粹靠 babel 或 esbuild 转译也能跑类型检查全程拖慢开发节奏可项目一到构建阶段又必须强制通过——于是每次开完 dev server大家都不敢执行外部工具命令生怕 CPU 被拉到 100%。我最初接手某跨平台管理系统时光 TypeScript 单独编译就要 40 多秒webpack 冷启动项目要两分半热更新单次峰值六到八秒。整个团队说到改类型定义就头疼每次 CI 构建还要额外花一分钟跑 tsc。后来我花了一个下午把工具链拆开重组整个优化过程拆解下来其实就是几个关键点识别瓶颈、切换编译策略、把类型检查挪到独立进程、启用缓存。今天我把这套“5 分钟调优”的思路完整写出来照着做大部分项目都能把编译等待时间砍掉一半以上。1. 先搞清楚慢在哪别再凭感觉优化做性能优化最忌讳一上来就换工具。你得先量化搞清楚时间到底耗在哪个环节。不然换了 esbuild 加了缓存结果慢点在场景切换的 webpack 插件里那就白折腾了。1.1 三种慢的类型要分别处理我习惯把 “TypeScript 编译慢” 拆成三种情况tsc 单独执行慢在命令行跑tsc --noEmit或tsc -p tsconfig.json整体耗时很长。这种典型是指数级增长的.ts文件类型推断以及大型依赖 .d.ts 合集导致的解析压测。webpack 构建慢跑npm run build时整体编译流程慢。这里面既有 TypeScript 转译慢也有其他 loader、插件、依赖打包的耗时需要拆开看。dev server 热更新慢每次保存文件后从变更到浏览器刷新的时间很长。这往往是 ts-loader 在每次编译时都做了全量类型检查或者 webpack 没有做增量编译。许多开发者的第一反应是“用 SWC 替换 tsc”但 SWC 只解决转译问题它不做类型检查。你的类型检查如果还是由某个插件或命令在执行该慢的还是会慢。所以第一步必须是度量。1.2 用数据说话tsc 和 webpack 各花多少秒先给项目做一份诊断报告。我这里给出几种最直接的方式1. tsc 自身的耗时诊断tsc --noEmit --extendedDiagnostics执行完会输出类似这样的统计信息Files: 1200 Lines of TypeScript: 85000 Options: 947 Projects: 1 Type checking time: 12.567s ...重点关注Type checking time和Total time。一般类型检查耗时超过 3 秒就要考虑改变策略了。2. webpack 构建耗时诊断用 speed-measure-webpack-plugin它对 webpack 4/5 都兼容。npm 安装后在 webpack 配置里包一层即可const SpeedMeasurePlugin require(speed-measure-webpack-plugin); const smp new SpeedMeasurePlugin(); module.exports smp.wrap({ // 你原有的 webpack 配置 module: { rules: [/*...*/] }, plugins: [/*...*/] });跑一次构建会输出每个 loader 和 plugin 的耗时占比。比如我之前遇到的项目ts-loader占了总时长的 67%而babel-loader几乎可以忽略不计。这时候你就明确知道了问题核心就在 TypeScript 类型检查这条链路。3. 如果页面在浏览器里打开慢那就看 network 面板和 devtools 的性能分析。不过这种情况通常是代码体积和 source map 的问题不在本文讨论范围。1.3 定位出关键矛盾编译 vs 类型检查诊断完你会发现几乎所有 TS 慢的本质都是类型检查而不是转译。转译其实就是把 TS 语法剥掉、变成 JS这一步骤 ESBuild、SWC、Babel 都能做到飞快但类型检查需要理解整个项目的类型图——某个接口改了可能十几个文件都要被重新验证一遍这没法用并行线程或者简单缓存解决。更隐蔽的问题是很多配置里类型检查被挂在了主构建线程上。以 ts-loader 为例它同时承担“转译”和“类型检查”两类工作且在 webpack 的 loader 流程里默认是同一个进程逐一执行的。转译可能只花 0.3 秒而后面的类型检查可能是 5 秒而且还会把 webpack 的整个构建流程卡住导致后续的 tree-shaking、压缩都没法启动。理解了这一点优化方向就非常清晰了。2. 核心方案拆解转译与类型检查分离既然慢在类型检查被同步阻塞在构建链路里那我们的核心策略就是“把转译和类型检查拆开”。转译交给最快的工具类型检查移到独立进程或者延后执行。2.1 ts-loader 的 transpileOnly一个开关省半小时绝大多数 webpack 项目都在用 ts-loader。它有两个关键配置transpileOnly: true仅做语法转译不做类型检查。transpileOnly: false默认转译 类型检查都做。当你打开transpileOnly之后ts-loader 只负责把.ts变成.js类型检查完全交给旁路进程。这一项改动往往能把构建时间缩短 60% 以上因为类型检查的耗时占比通常远大于转译。下面是一个常见的 webpack 5 配置片段// webpack.config.js const ForkTsCheckerWebpackPlugin require(fork-ts-checker-webpack-plugin); module.exports { module: { rules: [ { test: /\.tsx?$/, loader: ts-loader, exclude: /node_modules/, options: { transpileOnly: true, // 关掉 load 内的类型检查 configFile: tsconfig.json, experimentalWatchApi: true, // 观察模式使用增量 API compilerOptions: { // 让 ts-loader 不做类型检查所有检查交给 fork-ts-checker } } } ] }, plugins: [ new ForkTsCheckerWebpackPlugin({ typescript: { configFile: tsconfig.json, diagnosticOptions: { semantic: true, syntactic: true } } }) ] };experimentalWatchApi这个选项在 watch 模式下很有效。某个大项目开 dev server 时打开这个开关能明显降低单次编辑的耗时。2.2 ForkTsCheckerWebpackPlugin把类型检查挪到独立进程用transpileOnly: true有一个硬伤类型检查彻底没了写错的类型在浏览器里不会报错只能在编译完成后的某个时间点统一爆出来。这对开发体验是致命的。所以我们需要 ForkTsCheckerWebpackPlugin。这个插件会用 Node 的child_process派生一个独立进程专门跑 TypeScript 的 semantic diagnostic。主线程webpack只做转译类型检查结果通过 IPC 异步返回。检查到错误后再决定要不要终止编译生产构建或输出错误列表开发构建。它的最大价值不是让检查消失而是让检查不再阻塞转译和打包。原本同步 6 秒的等待现在变成了转译 0.5 秒先完成webpack 继续打包类型检查的结果在 3 秒后异步送回来——如果你开启了build模式且检测到错误它仍然会在最后失败但前面的打包流程没有被卡死。有一个小经验如果项目很大比如有 2000 个 ts 文件建议给 fork-ts-checker 分配专门的memoryLimit否则检查进程经常会因为内存占用过高被系统杀掉new ForkTsCheckerWebpackPlugin({ memoryLimit: 4096, // 单位 MB typescript: { configFile: tsconfig.json, build: true // 增量类型检查类似 tsc --build } })2.3 更快的转译方案babel 或 esbuild-loaderts-loader 就算transpileOnly底层调用的还是 TypeScript 编译器tsc来做语法转译。它比 esbuild 和 swc 要慢不少。如果你对性能有更高要求可以直接用 esbuild-loader 来替代 ts-loader 的转译职责。一旦你决定用 esbuild-loaderts-loader 可以直接删掉规则如下const EsbuildPlugin require(esbuild-loader); module.exports { module: { rules: [ { test: /\.tsx?$/, loader: esbuild-loader, options: { loader: tsx, // 按需jsx/tsx target: es2018 } } ] } };esbuild 用 Go 编写转译速度是 tsc 的 10~20 倍。它不支持类型检查所以同样要配合 ForkTsCheckerWebpackPlugin。官方文档里也建议这种组合。我的实测数据某个 1200 个 TS 文件的模拟项目 Xts-loader fork-ts-checker 模式转译耗时约 1.8 秒esbuild-loader fork-ts-checker 模式转译耗时约 0.4 秒。类型检查时间不变但构建总体时长减少了 1.4 秒。这里要注意esbuild-loader 处理 Decorator 或某些非标准 TS 特性时可能有兼容问题。如果你的项目用了需要Reflect.metadata的 DI 框架或者启用了自定义 TS Transform请先测试。esbuild 默认支持experimentalDecorators但有些复杂的emitDecoratorMetadata行为并不完全等价于 tsc。理解这一点很重要我们不是要“完全等价”而是“够用就行”。大多数业务系统用不到 tsc 特有的高级装饰器元数据。3. 5 分钟实操优化一个真实 webpack TS 项目这一节是针对 webpack ts-loader 项目的完整优化流程。我假设你项目没有任何额外的编译魔法以业务代码为主。整个流程按顺序执行每一步都能看到变化。这里的“5 分钟”是指你照着操作的时间不是说优化效果只有 5 分钟。实际上优化完寿命比你想象中要长。3.1 第一步写一份“编译专用 tsconfig”这里的思路是把项目里的 tsconfig 分为“类型检查用”和“构建用”。构建用的 tsconfig 打开transpileOnly并且关闭所有类型推断损耗大的选项。比如项目原本的tsconfig.json{ compilerOptions: { target: ES2018, module: ESNext, strict: true, skipLibCheck: false, noEmit: true, jsx: react-jsx, esModuleInterop: true, forceConsistentCasingInFileNames: true }, include: [src] }编译专用版本tsconfig.build.json{ extends: ./tsconfig.json, compilerOptions: { noEmit: false, skipLibCheck: true, declaration: false, declarationMap: false, sourceMap: false }, include: [src] }为什么要单独一份因为skipLibCheck可以大幅减少类型检查过程中对.d.ts文件的解析。如果你项目引用了较大体积的库比如包含完整罗马字符映射表、I18n 语言包之类这个开关能把类型检查时间缩短 20% 到 30%。而编译本身不需要对 .d.ts 文件做任何处理所以构建用的配置完全可以打开它。noEmit: false在有 webpack 的情况下TL;DR 就是告诉 tsc 你不用管输出文件webpack 会处理。有些项目会同时让 tsc 输出 d.ts那就不设noEmit但建议不要在构建过程里混用。我怎么做的在package.json里把tsc -p tsconfig.build.json --noEmit去掉让构建真的交给 webpack。3.2 第二步改动 webpack 配置明确了策略后一次修改 webpack 配置文件。我以 webpack 5 React ts-loader 为例先看完整的配置const path require(path); const ForkTsCheckerWebpackPlugin require(fork-ts-checker-webpack-plugin); const HtmlWebpackPlugin require(html-webpack-plugin); module.exports (env, argv) { const isDev argv.mode development; return { mode: env.prod ? production : development, entry: ./src/index.tsx, output: { path: path.resolve(__dirname, dist), filename: [name].[contenthash].js }, resolve: { extensions: [.ts, .tsx, .js, .json] }, module: { rules: [ { test: /\.tsx?$/, exclude: /node_modules/, loader: ts-loader, options: { transpileOnly: true, configFile: tsconfig.build.json, experimentalWatchApi: true } } ] }, plugins: [ new HtmlWebpackPlugin({ template: ./public/index.html }), new ForkTsCheckerWebpackPlugin({ typescript: { configFile: tsconfig.json, // 完整配置用于类型检查 diagnosticOptions: { semantic: true, syntactic: true } }, async: isDev // dev 模式下异步构建模式下同步报错 }) ], cache: { type: filesystem, cacheDirectory: path.resolve(__dirname, .node_cache/.webpack), buildDependencies: { config: [__filename] } }, devtool: isDev ? eval-cheap-module-source-map : source-map, optimization: { splitChunks: { chunks: all } } }; };这里需要理解三个关键变化第一transpileOnly: true的配置从原 tsconfig 中分离。类型检查用tsconfig.json的完整配置做。构建用tsconfig.build.json其中skipLibCheck已经打开。第二fork-ts-checker的async选项在开发模式中设为 true。意思是开发模式下类型错误不会阻塞页面的热更新webpack 把转译结果照常输出浏览器更新 UI类型错误只在 terminal 异步报出来。生产构建中设为 false一旦类型错误构建直接失败。这样既保证开发体验又避免把错误带上线。第三webpack 5 的cache改为文件系统缓存。默认的 memory cache 在重启 dev server 后就会丢失但文件系统缓存能跨 dev server 重启保留。对于 ts-loader 本身来说cache 是否对它生效取决于它是否实现了持久化缓存。实际上transpileOnly加 webpack 文件系统缓存第一次构建依旧需要完整转译但第二次之后如果源码没变化会直接复用之前的模块编译结果。这一步在重启项目时非常明显冷启动从原来的 60 秒降到 25 秒左右。3.3 第三步contributing 给 vite 项目换个思路如果你的项目用 vite优化的就完全不一样了。vite 默认用 esbuild 做转译已经很快。但 vite 在 dev 模式下不会做类型检查生产构建时使用的也是 esbuild 转译所以它几乎没有“编译慢”的问题。真正慢的环节通常是依赖预构建node_modules和类型检查命令。vite 项目如果觉得 dev server 首次加载慢可以检查optimizeDeps.exclude和include配置。举个例子如果项目里引用了某个很大的组件库的完整入口依赖预构建要把所有依赖编一遍可能首次启动就多等八秒。这时你可以把大的库加入optimizeDeps.include并开启force预构建一次。但这不是本文重点。我想说如果你是在已有 webpack 项目上做优化按刚才的流程就够。如果是从零开始新项目完全可以选用更轻量的方案。比如直接用viteSWC插件或tsup来打包 CLI 工具根本不需要经历 webpack 这一层。3.4 第四步加缓存和并行压缩webpack 的cache: { type: filesystem }能解决重启问题但构建过程中的压缩阶段比如 TerserPlugin也会占用大量时间。如果你的项目 JS 代码量超过 5MB建议让 TerserPlugin 开启多线程压缩const TerserPlugin require(terser-webpack-plugin); optimization: { minimize: true, minimizer: [ new TerserPlugin({ parallel: true, terserOptions: { compress: true, mangle: true } }) ] }parallel默认开启但你可以在配置里显式声明避免不同环境下的差异。实际上 webpack 官方推荐 build 中使用 TerserPlugin 做代码压缩但它处理的如果是 TS 转换后的 JS依旧与 TS 编译无关。如果构建输出本身很大这一项也能节省不少时间。不过要注意多线程压缩会增加内存占用如果你的 CI 机器内存只有 2GB建议不要开启parallel否则可能 OOM。4. 常见问题与排查技巧实录优化完并不是终点我在实际操作中一定会遇到一些奇奇怪怪的坑。下面是我整理的问题速查表按出现频率排序。症状原因解决办法开启 transpileOnly 后代码里明显的类型错误不再报错没配 ForkTsChecker 或配置未生效确认插件已添加且 typescript 配置指向含有完整检查项的 tsconfigfork-ts-checker 报内存不足大项目类型检查占用内存过多提高 memoryLimit或在 tsconfig 中设置keyofStringsOnly降低复杂度使用了 esbuild-loader构建成功但运行时出现装饰器报错esbuild 对 emitDecoratorMetadata 支持不完整项目复杂装饰器场景下回归 ts-loader或换用 SWC 并开启decrcoratorMetadata类型检查比之前更慢因为 fork-ts-checker 进程也在做全量检查且没有增量缓存打开build: true让 fork-ts-checker 使用 tsc --build 的增量编译模式文件系统缓存在 CI 上反复失效缓存目录被清理或者 project reference 改了在 CI 上可设置固定缓存 key本地开发则把 cacheDirectory 放到 node_modules 同级并加入 gitignoredev server 热更新时错误不能及时显示async 设为 true 且类型检查结果异步滞后在编辑器或命令中手动执行tsc --noEmit或在 dev 环境也把 async 设为 false但会牺牲热更新速度下面挑几个典型的坑详细讲一下4.1 坑一类型检查“消失”了很多人在 webpack 配置里把transpileOnly改成 true 后发现终端不再输出类型错误第一反应是“检查被干掉了”然后又把ForkTsCheckerWebpackPlugin加回来但还是没报错。这时候需要检查一下fork-ts-checker的typescript.configFile是否被你改成了tsconfig.build.json。因为如果你让 fork-ts-checker 使用构建专用配置其中skipLibCheck: true是合法选项但如果你把include只指向src它确实会只检查源码正常情况下也会报错。更大的可能是你的webpack.config.js里 ts-loader 的configFile和 fork-ts-checker 的configFile指向的是同一个文件但那个文件里的noEmit为 true。ForkTsChecker 有一种行为如果检查的 tsconfig 设置了noEmit: true它不会执行常规 check而会直接跳过。这是什么逻辑其实在一些旧版本里noEmit 配置下它不会做 semantic diagnostics。解决办法给 fork-ts-checker 单独传入一个不包含noEmit的 tsconfig或者在 plugins 里显式定义typescript: { configFile: tsconfig.json, diagnosticOptions: { semantic: true, syntactic: true } }。4.2 坑二增量编译失效fork-ts-checker 有个 issue如果你在项目里用了多个 tsconfig比如一个 root 配置文件一个 build 配置文件它默认只用 root 的那个做检查。而 root 配置中有composite选项或references时build: true可能会因为校验失败而回退到全量检查。解决方式是明确告诉它使用增量模式new ForkTsCheckerWebpackPlugin({ typescript: { configFile: tsconfig.json, build: true, mode: write-tsbuildinfo } })write-tsbuildinfo模式会把.tsbuildinfo写到磁盘上下次复用其中的版本信息来做增量。但注意如果你经常改动 tsconfig 中的paths或baseUrltsbuildinfo 的缓存可能会误判建议在改动 tsconfig 时顺手删一下缓存目录。4.3 坑三node_modules 里的类型错误被当成了项目错误类型检查范围包含 node_modules特别是某些库没有写好 .d.ts其实不该让它们阻塞你的构建。稳妥做法是在 tsconfig 中把skipLibCheck设为 true同时把include限到src。但fork-ts-checker默认会解析整个项目如果你引用了某个大库的错误类型检查起来会慢而且可能报出你根本改不了的错误。我的经验是在 fork-ts-checker 的typescript选项里加一个build: true并且加上typescriptPath: require.resolve(typescript)可以避免多版本 TypeScript 被插件混淆引用的问题。4.4 坑四盲目使用 esbuild结果项目跑不起来esbuild 的转译速度确实快但它的目标输出不会包含类型相关的 JS 代码比如没有降级转换const enum、没有importsNotUsedAsValues之类的高级支持。如果你的项目里大量使用const enumesbuild 默认就会直接报错或内联出错。importsNotUsedAsValues这种边角问题也很常见。真正稳妥的方案是先把 ts-loader transpileOnly 这一套跑通这已经能带你解决 80% 的问题。等到你觉得还不够快再考虑 esbuild / swc。千万别一上来就追求“极致”否则你的调优时间可能比省下的构建时间还长。5. 从“5分钟”到长期维护缓存与增量编译的进阶玩法如果你已经跑通了上面这套流程还有余力继续挤压构建时间这里有几个进阶技巧。它们不需要做大的配置调整但对大型项目或 monorepo 项目收益明显。5.1 利用 TypeScript Project References 做项目级增量如果你的项目拆成了多个子包比如packages/ui、packages/utils、packages/core可以考虑给每个子包单独建 tsconfig再用references引入。这样类型检查可以按包粒度增量触发只有改变过的模块才会重新检查。操作思路是// tsconfig.json (root) { files: [], references: [ { path: ./packages/core }, { path: ./packages/utils }, { path: ./packages/shared } ] }每个子包的 tsconfig 需要设置composite: true。然后在构建时执行tsc --build它会自动并行构建所有子包并且只重新构建改变的部分。如果你的团队还没有拆分包这一步可以暂时不碰因为它会改变你整个项目的构建拓扑收益虽大但迁移成本也不小。5.2 增量缓存 tsbuildinfo 文件即使不用 monorepo也可以启用增量编译。在 tsconfig 中加入{ compilerOptions: { incremental: true, tsBuildInfoFile: ./.cache/tsbuildinfo } }之后如果 fork-ts-checker 的build模式配置正确它会在每次检查时读取这个缓存文件。注意这个缓存是给 tsc 的--build用的如果 webpack 本身的cache配置也没有问题两者叠加可以做到真正的“只编译变更文件”。我见过的很多项目根本没有利用 tsbuildinfo开了incremental也没意义因为每次 dev server 重启后.tsbuildinfo并没有被有意存放。正确做法是把它放入一个持久化的缓存目录同时加入.gitignore。5.3 使用 SWC 代替 tsc先确认收益前面提到 esbuild-loader 是一种加速方式SWC 同理。许多人会问“既然 SWC 这么快为什么不直接全项目用 SWC”其实 SWC 在转译层面具备完整 TypeScript 语法支持且已经支持装饰器元数据但它同样不做类型检查所以它和 esbuild 在 webpack 场景的收益类似。想要真正利用 SWC 的增量优势可以考虑这套组合用swc-loader替代 ts-loader/esbuild-loader保留ForkTsCheckerWebpackPlugin做类型检查配合 webpack 文件的持久化缓存实测下来SWC 与 esbuild 的转译速度不相上下但 SWC 对 decorator 和更老语法兼容性更好。如果你的项目里有一些老旧框架依赖装饰器选 SWC 风险更低。但代价是它需要 Rust 编译出的原生模块装包时会带着二进制依赖在 CI 环境下有时网络受限会导致安装慢这通常不是大问题。5.4 从构建中彻底剥离类型检查极其适合运维后台有一种极端但有效的方案在 dev 和 build 阶段完全不做类型检查只在 Git 提交时或 CI 上单独跑一次tsc --noEmit。这样能保证开发过程绝对流畅同时保证交付前的质量关卡。操作很简单去掉 ForkTsCheckerWebpackPlugin把transpileOnly或 esbuild-loader 配置好在 package.json 中增加一条脚本{ scripts: { typecheck: tsc --noEmit, prebuild: npm run typecheck } }生产构建时prebuild会自动执行类型检查检查失败则构建失败。dev 开发时你完全不需要跑 typecheck想检查了手动执行一下即可。这种方案的缺点是不能在编码过程中实时获得类型反馈。但如果你是个人项目或者团队依赖编辑器自带的 TS Server 提示编辑器通常也用 tsc 后台检查那么 webpack 里的类型检查其实是重复的。编辑器已经在报红构建再报一次没有太大意义。很多资深开发者早就这么做甚至把prebuild的 typecheck 做成一个可选 npm 脚本默认不跑只在 CI 上跑。这个技巧非常管用但需要内部约定否则容易忽略类型检查。6. 拿我自己的项目开刀优化后的时间对比最后放一份我在某模拟项目1200 个 TS 文件、85 个组件、38 个工具库上的实测数据方便你感知每种策略的收益。方案冷启动秒热更新秒构建完成秒初始ts-loader 默认654.8150方案Ats-loader transpileOnly fork-ts-checker331.985方案Besbuild-loader fork-ts-checker220.962方案C方案B webpack 文件缓存 tsbuildinfo120.345方案D方案C prebuild 独立 typecheck90.340注意这只是单次实验的结果具体项目差异可能很大。但只要把 ts-loader 默认模式换掉效果就是肉眼可见的。我个人在实际操作中最推荐的路径先用方案 A 把项目跑顺稳定运行一周后再升级到方案 C。不要一步到位用 esbuild因为你可能在第二天就碰到某个 TS 高级特性不兼容的问题而且在“全链路加速”的情况下排查起来会非常麻烦。一步一步来每改一个环节都先跑一次本地测试和一次生产构建心里才有底。最后再补充一个小技巧如果你在 dev 模式用了eval-cheap-module-source-map构建过程会生成 source map实际上也会拖慢热更新。想要最快热更新可以试试devtool: eval或直接不设置 devtool。但代价是错误堆栈的可读性下降。我的折中方案是开发用eval-cheap-module-source-map只有遇到需要精确定位到源码行列号时才切换到source-map模式排查完再切回来。这个选择往往比编译器优化更影响日常手感。TypeScript 项目编译慢核心问题十有八九就是我们死守着“全量类型检查”这条旧路线不放。一旦你接受了“转译归转译类型检查归类型检查”这种理念剩下的优化路径立刻清晰起来。希望我这套实操经验能帮你把宝贵的几分钟从终端等待中抢回来留给自己倒杯水。