Webpack 统治前端工程化的时间太久，久到很多团队已经把“项目复杂就必须上 Webpack”当成默认选项。但项目一旦过了某个规模，Webpack 的配置膨胀、构建变慢、调试链路拖泥带水，就会成为开发效率最直接的阻碍。用 TS + tsup + Vite + Rolldown 这套组合拳，可以把类型检查、库打包、开发服务器、生产构建这几件事拆开，让每个工具只负责自己最擅长的一段。这篇文章不是劝你立刻删除 Webpack，而是给正在维护老项目、想改善构建体验的前端团队一条更稳妥的落地路径。我先说核心判断：这套组合的真正价值不是“换了一个工具”，而是重新划分了构建任务的边界。
1. 为什么 Webpack 项目越维护越累：配置熵在积累
1.1 Webpack 的复杂度来自叠加而不是单个功能
Webpack 的强大来自 loader 和 plugin 的叠加。你可以用它处理几乎任何资源，但代价是每当新增一种资源、一种入口、一种环境，配置里都会多一层规则。项目两三年后，配置文件里往往积压了大量历史配置：有的 loader 被新版替代了还没删，有的 alias 指向的目录早就重构完，有的 externals 只有线上构建才用到。
我见过不少团队里，Webpack 配置已经成了“禁区”。新同事不敢动，老同事也说不清每条配置为什么存在。真正影响效率的往往不是构建那几分钟，而是每次配置变更后的不确定性：改了会不会影响线上产物？会不会影响某个老入口？这种心理压力会让人越来越抗拒调整构建链。
1.2 public 目录和静态资源路径，最容易踩的隐形坑
使用 Webpack 时，常见这么一句提示：“content not from webpack is served from .../public”。意思是，public 目录下的文件会被原样拷贝，不参与 Webpack 的依赖图谱。很多项目把图片、字体、favicon 放进去，业务代码里直接写/img/logo.png这种绝对路径。本地没问题，推到线上后如果部署到子路径，或者 CDN 路径带前缀，图片就 404。
这不是 Webpack 能力不够，而是它的资源处理模型给了太多“自由选择”，很多选择最后都变成了线上的路径问题。换到 Vite 之后，public 目录的约定仍在，但引入资源的推荐方式更统一：通过 import 引用，构建时自动处理 base 路径。如果确实要放 public，就必须在配置里把 base 设好。这样至少把“到底该用哪种路径”这个问题收敛了。
1.3 小组件、多包项目、老插件互相拖累
在单体应用里，Webpack 的问题会被集中放大：业务代码、公共组件、内部工具库都塞进一个构建链路里。每次改一个内部小工具包，要经过整个 Webpack 构建链路；每次升级一个插件，都要检查是否影响到所有入口。
当项目里出现“开发编译等 40 秒、热更新 3 秒起步”的现象，通常不是硬件问题，而是构建链路上的资源被过度集中了。工具链拆开之后，至少要让不同性质的代码走不同路径，不要所有东西都挤在一个构建流程里。
2. 组合拳分工：TS、tsup、Vite、Rolldown 各自解决哪一段
2.1 tsup：库打包首选，简单到不需要额外框架
tsup 基于 esbuild，使用方式接近“一个入口文件进去，ESM/CJS/声明文件出来”。如果你要写一个独立工具函数库、组件库或者业务公共包，tsup 是我目前最推荐的一种选择，因为它把 Webpack 里最耗时的多入口、多格式、d.ts 生成这些事都封装好了。
一个很常见的场景：团队内部有多个前端项目共享一个工具包，以前用 Webpack 打包成 dist，再被 app 引用。每次工具包更新都要重新构建一次，构建配置还跟着主项目一起变大。换成 tsup 后，一个配置文件、一条命令，ESM 和 CJS 同时产出，.d.ts 自动生成，app 端接入也干净很多。
2.2 Vite：开发体验的改善最直观
Vite 开发服务器可以理解为“按需编译 + 预构建”的组合。它先用 esbuild 把 node_modules 里的依赖预先 bundle，源文件则保持原生 ESM，浏览器请求到哪个模块才编译哪个。冷启动速度和 HMR 速度，相比传统 Webpack 的热更新通常有直观提升。
注意，Vite 生产构建默认使用 Rollup，而不是 esbuild。esbuild 主要用在开发阶段和依赖预构建。生产构建要做得精细，比如代码分包、CSS 抽取、静态资源指纹，还是要看 Rollup 配置。很多人刚切到 Vite 时以为 production build 会默认得到极致优化，实际上还是要花时间调整。
2.3 Rolldown：给生产构建这环预留的加速引擎
Rolldown 可以理解成“用 Rust 重写、兼容 Rollup 接口的生产构建引擎”，它是 Vite 生态里一个明确的演进方向。目标是让 Vite 的开发体验和生产构建性能保持统一，而不是开发阶段飞快、生产构建又退回到 Rollup 的年代感。
对于普通项目，现在不一定立刻切换到 Rolldown。但要留意这个方向：如果你正在设计新项目的构建链，就不要把 Vite 当成一个不能再动的黑盒，它的生产构建是可以在未来替换成 Rolldown 的。团队选型时，更应该关注配置和组织方式是否可以平滑迁移。
2.4 TypeScript 的位置：类型检查不能等同于转译
组合拳里最容易误解的是 TypeScript 的职责。tsc、esbuild、swc、Babel 各自能做不同类型的事。esbuild 在转译 TS 时非常快，但它默认不做类型检查，类型错误不会出现在构建日志里。看到ts文件能跑起来，不等于类型是安全的。
所以完整链路应该是：开发阶段用 esbuild 转译保住速度，CI 里至少跑一次tsc --noEmit做严格类型检查，发布公共库时再让 tsup 输出 .d.ts 类型声明。这三件事，不能只指望一个命令全包。
3. 从 Webpack 迁到 Vite + tsup 的落地顺序：先开发，后构建，再拆库
3.1 先切换开发服务器，保留 Webpack 生产构建
直接一步切掉 Webpack 风险很大。我的建议是分两阶段：第一阶段只把开发服务器换成 Vite，生产构建暂时用 Webpack；第二阶段等开发环境稳定后，再切换生产构建。
第一阶段要盘点的东西其实不少：
- 路由模式：history 模式需要 dev server 的 fallback 配置。
- 环境变量：Vite 默认只暴露
import.meta.env以及以特定前缀开头的变量，要确认业务代码里读取方式是否需要兼容。 - 代理：
devServer.proxy要翻译成server.proxy。 - 全局变量：老代码如果依赖
process.env，需要在 Vite 里做 define 或使用兼容写法。 - 静态资源：public 目录、图片路径、字体文件逐个确认。
这段切换期，肉眼最明显的收益是热更新速度。Webpack 下 2-3 秒起步的热更新，在 Vite 里很多时候是毫秒级，长页面反复调试时体感差别很大。
3.2 生产构建切换到 Vite 时，重点检查分包和产物路径
开发服务器没问题后，再做生产构建切换。Vite 的 build 默认用 Rollup，整体产物结构会比 Webpack 简单，但需要重新审视几件事：
base一定要设置正确，否则部署到子目录或 CDN 后静态资源 404。build.outDir、assetsDir是否需要定制。build.target决定转译目标，所谓“现代浏览器优先”不是无代价的。- 代码分包：Webpack 里 splitChunks 的复杂规则，在 Rollup 里通常用
output.manualChunks来表达，语义要清晰得多，但也别过度拆分。 - 老项目里的
html-webpack-plugin、copy-webpack-plugin等能力，在 Vite 里有对应的原生选项或插件。
有一个容易忽略的点：Webpack 里的publicPath和 Vite 的base不是完全等价。base还会影响 html 里的资源引用、路由 history 模式下的基础路径。建议在测试环境先部署一轮，人工点一遍页面再上线。
3.3 公共库和内部包交给 tsup，主应用保持极简
如果项目里已经有内部工具包、组件库或者公共方法集，我建议把它们从主应用构建链里拆出去，交给 tsup。一个典型流程：
# 示例：tsup 基本输出 tsup src/index.ts --format esm,cjs --dts --out-dir dist这样主应用不需要为这些内部包重复做一次打包解析，内部包自己维护格式、类型声明、版本。发布流程也可控：先构建，再发布到内部镜像源，主应用升级依赖版本即可。对于多人协作，比“代码直接引用另一工程目录”更清晰。
3.4 代理配置的迁移，最容易在接口层翻车
切换到 Vite 后，开发代理翻车很常见。比如本地请求/api/form/list时，控制台出现类似http proxy error: /api/form/list?page=1&pagesize=10的报错。这个报错看着像代理本身有问题，但实际要先确认后端 target 是否可达，再看路径是否带了正确前缀，最后看代理配置的 changeOrigin、rewrite 是否正确。
排查顺序应该是：目标地址能不能访问，然后再看前端配置。我在迁移时习惯先写一个最小代理配置，把接口代理到测试环境，跑通一个列表接口后再添加更多规则。不要一次性把所有代理规则都搬过去，否则出问题很难定位。
4. 关键配置和参数：先理解再照抄，不要无脑复制
4.1 tsconfig：和构建工具配合的几个关键项
用 Vite 或 tsup 时，tsconfig 里的module、moduleResolution不要照搬 Node 项目的写法。常见组合：
{ "compilerOptions": { "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true, "declaration": true } }"module": "ESNext"让代码保持 ESM 语义，具体转译交给 esbuild；"moduleResolution": "Bundler"用于兼容写@/xxx这种别名引用，需要tsconfig里同时声明 paths。skipLibCheck通常建议打开，否则第三方包的类型问题会干扰你排查。
noEmit很关键：用 Vite 开发时，TSC 不应该负责产出 JS 文件，它只负责类型检查。如果配置里还按老 Node 项目写outDir、noEmit: false，容易产生多余的编译产物，还会和工具链的转译重复。
4.2 vite.config：开发服务器和构建的最小骨架
export default defineConfig({ base: '/', resolve: { alias: { '@': '/src', }, }, server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, ''), }, }, }, build: { outDir: 'dist', target: 'es2019', sourcemap: false, }, })这里base建议从第一版就设置成部署环境的真实路径，不要默认根路径后期待改。proxy.rewrite很关键：如果后端接口不带/api前缀，就需要把它去掉；如果带，就不要 rewrite。
4.3 tsup.config：公共库构建
import { defineConfig } from 'tsup' export default defineConfig({ entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true, sourcemap: true, clean: true, target: 'node18', })format指定输出格式，dts: true生成类型声明。库文件一般要考虑 tree shaking 支持，ESM 格式要优先，CJS 格式主要用于兼容老构建链路。clean会在每轮构建前清空输出目录，避免旧文件残留。
4.4 代码混淆不是构建工具的默认职责
“Vite 打包代码混淆”是一个高频搜索词。Vite 默认的 build 过程会压缩代码，通常会移除非法字符、缩短变量名、做 tree shaking，但这不是安全意义上的混淆。如果需要更高强度混淆，得单独引入混淆插件，并评估性能损失和线上调试成本。
这里要提醒一句：混淆不等于安全，只能增加逆向成本。如果项目依赖权限校验和后端安全策略，不要把防破解寄托在前端混淆上。真要做，也应该在 CI 里把 sourcemap 和混淆插件的开关管理好，避免把混淆后的产物直接发布到 CDN 却无法排障。
5. 判断这套组合是否值得：认准冷启动、热更新、生产构建三个指标
5.1 冷启动：看从启动命令到能访问页面的时间
这个指标最能体现开发服务器的取舍。Webpack 通常是先构建整个依赖图再启动，项目越大启动越慢；Vite 是预构建依赖 + 按需编译源文件，启动速度通常更快。测量方法很简单：执行 dev 命令，记录日志里出现 ready 的时间，然后浏览器打开页面看首屏是否正常。
如果是多人协作项目，还可以看团队成员切换分支后重复冷启动的体验。频繁切分支、频繁重启 dev server 的工作流，对冷启动速度非常敏感。
5.2 热更新：不要只看日志，要看页面更新时间
HMR 的体验和业务代码组织方式有关。在 Webpack 里，一个组件改动常常触发整个 chunk 更新；Vite 里按模块更新，改进更明显。但要注意，如果业务代码里大量使用副作用模块、顶层循环、全局变量，HMR 效果会被削弱。先保证代码模块边界清晰，再谈工具优化。
有一个统一判断标准：改一个组件的 props，从保存文件到页面看到结果，超过 1 秒就已经算长了。如果切到 Vite 后仍然要 2-3 秒，大概率不是工具问题，而是业务模块之间耦合过重。
5.3 生产构建：最不能只看总耗时
有些人切到 Vite 之后发现生产构建总时间没有特别大下降，就开始怀疑工具是否真的更快。其实要看更细：构建分成 bundle 前的转录、代码分析、压缩、tree shaking 几个阶段。如果只是压缩占了大头，换构建引擎影响不大。
而且生产构建的核心指标不只是时间，还有产物稳定性、CSS 顺序、分包合理性、sourcemap 是否可用。建议用下面这张表对比：
| 指标 | 说明 | 判断标准 |
|---|---|---|
| 构建总耗时 | 从执行 build 到产物生成 | 同一机器前后对比，别用笔记本合盖状态对比 |
| 产物体积 | 各 chunk 体积、总包大小 | 关注首屏加载 chunks，不是看 dist 总大小 |
| 静态资源数 | js、css、图片、字体文件数量 | 数量过多可能意味着分包策略有问题 |
| 构建成功率 | 连续多次构建是否稳定 | 多跑几次，看是否偶发失败 |
| Sourcemap 可用性 | 线上报错能否定位到源码 | 生产环境可考虑关闭或单独上传 |
判断建议：每次构建可以看构建总耗时、产物体积、首屏资源数量、静态资源文件数。迁移前后对比时，用同一个输入代码、同一台机器、同一个压缩参数，才有可比性。不要在本地网络波动大的时候跑对比，也不要一边跑构建一边开视频会议，数据会失真。
6. 高频报错和排查链路：遇到问题先看现象再动配置
6.1 proxy error 的排查顺序
迁移到 Vite 后，接口代理报错最常见。看到http proxy error: /api/form/list这类日志时，按下面这个顺序排查，比自己乱改配置快：
- 先用 curl 或浏览器直接访问 target 地址，确认后端是否真的可达。
- 看路径：后端接口是
/api/form/list还是/form/list，proxy.rewrite有没有处理。 - 看 target 是否带路径前缀，历史项目经常在 target 后面多写一段路径。
- 开代理调试日志，确认真实转发的目标地址。
- 最后才动前端代理配置。
很多 team 卡在这里的原因不是代理语法不会写，而是后端接口本身就没通。所以先访问 target，比改前端配置靠谱得多。
6.2 依赖和版本问题
换构建工具后最恼人的报错，很多都跟依赖有关。比如Cannot find package 'vite'这类问题，几乎都是 node_modules 安装不完整或版本不匹配，先在项目根目录重装依赖，再检查 package manager 的 lockfile 是否包含新工具链。
另一个常见问题是某些依赖只支持 CommonJS，在 Vite 开发环境会走到预构建逻辑；如果预构建出错，会看到 esbuild 相关日志。不要直接认为是源码问题，先确认依赖本身是否与入口格式兼容。Vite 还提供一些调试开关，比如vite_cjs_trace=true vite dev之类，用于定位 CJS 依赖调用链，遇到这类坑时可以打开看看，能更快找到是哪个依赖在运行时调用了不存在的变量。
6.3 迁移后白屏、404、路径错乱
出现白屏或 404，优先检查三件事：base是否匹配部署路径，路由模式是否需要 fallback，静态资源引用方式是否是绝对路径。Vite 自带 SPA fallback 用于 history 模式，但生产部署到 Nginx 时，需要服务端把未知路径回退到 index.html。
还有一个比较隐蔽的问题：老项目里用了window.location.origin或者拼字符串的方式生成静态资源路径，迁移后这些地方不会自动跟随 Vite 的 base 变化。全局搜索一下这类写法，改成用import.meta.env.BASE_URL或者入口处统一配置的变量。
6.4 TS 和类型声明的问题
用 TS 封装 axios 时，一个很典型的点：请求函数要返回明确的响应类型，而不是 any。很多项目把 axios 封装写得很顺手，但响应类型缺失，导致调用处完全靠猜。迁移到新工具链后，可以顺手把这类封装改成泛型：
async function request<T>(config: AxiosRequestConfig): Promise<T> { const res = await service.request<ApiResponse<T>>(config) return res.data.data }这样调用时能拿到类型提示，开发体验比 Webpack 时代更好。ts interface、ts partial这些基础概念不用多讲，但工具链迁移的时候，正好是补类型债务的时机。我在迁移几个项目时发现，顺手把 axios 封装、路由 meta 类型、环境变量类型都定义好之后，项目整体的类型体检会明显上一个台阶。
7. 边界和适用场景：不是所有项目都要立刻换
7.1 什么样的情况继续用 Webpack
如果你的项目依赖非常老的 Webpack loader 或 plugin，构建产物比较复杂，团队也没有足够时间做迁移验证，那强行换 Vite 反而会带来风险。尤其是老系统里使用了大量自定义 loader 逻辑、运行时把非模块文件当模板处理的场景，迁移成本可能比收益还高。
另一个场景是纯 Node 服务端项目。Webpack 用于 Node 构建不是不可以，但多数情况下直接用 tsup、tsc、tsx 等更简单。如果没有明确的浏览器侧资源处理需求，不要为了“统一构建工具”而引入重配置。
7.2 渐进式迁移比一刀切安全得多
新项目直接上 Vite + tsup 很方便；老项目建议先做评估，用一个小模块或新页面作为试点，用两到四周观察开发体验和构建稳定性。确认稳定后再扩大范围。
公共库模块可以用 tsup 先拆出去，主应用继续用 Webpack，等生产构建方案完全验证后再切。这样可以避免“所有东西一次性重写”的巨大风险。
如果团队里有多种历史构建配置，我建议先做一次清单：有哪些入口、哪些特殊资源、哪些自定义构建行为。没有这个清单之前，不要开始迁移。清单做完，很多坑其实已经提前暴露了。
7.3 未来的判断：构建工具会继续演进，但“分工拆开”是共识
Rolldown 的出现说明一件事：开发体验和生产构建性能是可以分开优化的。未来工具链大概率会继续向“更贴近原生、更细分场景”的方向演进。对大多数团队来说，不需要追最新版本，只要保持代码模块边界清晰、类型检查独立、打包配置尽量薄，就能在工具换代时少踩很多坑。
我的建议是：先把手头项目的最小构建链路跑通，记录几个关键指标，再决定是否引入新工具。这套组合拳的核心不是让你换一个“更潮”的构建器，而是让你重新理解前端构建里到底哪些环节值得投入、哪些环节可以简化。真正落到项目里，最该盯住的不是功能列表，而是输入格式、资源占用和失败重试。先把单任务跑稳，再考虑批量和接口改造，最后再谈工具全面切换。
