拓冰网站定制 
没经历过 Webpack 构建时间从 40 秒降到 3 秒、产物体积从 2MB 减到 800KB 的过程你很难对“构建优化”这件事有实感。Webpack 5 发布已经有段时间了但大部分项目其实还停留在“能用就行”的状态每次 npm run dev 都要等半天vite 用户茶余饭后的笑柄线上包越打越大首屏加载越来越慢领导问起来只能支支吾吾。这标题看着像要聊原理其实核心就两件事启动慢怎么治、体积大怎么减。这篇内容不整虚的我把实战里用得上的方案、配置、踩过的坑分门别类整理出来按步骤抄就能见效特别适合手里正维护 Webpack 项目、想升级到 Webpack 5 或者已经在 Webpack 5 里挣扎的团队参考。这篇博文很长但我保证没有一个字是凑数的。先从“为什么会慢、为什么会大”开始说起因为不搞清楚病根后面所有优化手段你都不知道为什么有效、哪些是白费力气。诊断有问题优化就是无头苍蝇。1. 先搞清楚你的项目到底慢在哪、大在哪很多人一上来就调配置结果折腾半天效果微乎其微问题就出在没做诊断。Webpack 构建慢和产物体积大的原因往往不止一个而且不同规模的项目瓶颈位置完全不同。我见过一个项目dev server 启动要 50 秒所有人以为是 loader 太慢结果一查是某个第三方库被错误地打进了依赖解析链路还有项目体积 90% 来自一个几乎用不到的图表库只是因为在入口文件里被默认导入了。不测量就优化等于蒙眼开车。1.1 用计时工具定位构建瓶颈Webpack 5 里做构建耗时分析的常见工具是speed-measure-webpack-plugin但这个插件和 Webpack 5 的兼容存在一些已知问题部分场景下会报错或者统计不出结果。我更推荐直接利用 Webpack 内置能力在webpack.config.js里临时包一层计时逻辑配合stats配置输出详细的耗时数据。// 临时调试脚本measure-build.js const { webpack } require(webpack); const config require(./webpack.config.js); webpack(config, (err, stats) { if (err || stats.hasErrors()) { console.error(err || stats.toString(errors-only)); return; } // 输出关键耗时指标 const info stats.toJson({ timings: true, modules: true, chunks: true, reasons: false, }); console.log(总耗时: ${info.time}ms); console.log(总模块数: ${info.modules.length}); console.log(总块数: ${info.chunks.length}); // 按耗时排序找出最慢的模块 info.modules .filter((m) m.profile m.profile.duration 1000) .sort((a, b) b.profile.duration - a.profile.duration) .slice(0, 20) .forEach((m) { console.log(${(m.profile.duration / 1000).toFixed(2)}s, m.name); }); });更直接的做法是启动 dev server 时加上--profile --json把输出的 JSON 扔进webpack --analyse可视化页面里看。但在实际操作里最朴素的方式反而是最有用的盯着终端输出看 Webpack 在哪个阶段卡住。编译过程分为resolve解析模块路径、loaders转换文件、pack生成代码、emit输出文件四个主要阶段。如果卡在 loaders说明 loader 处理慢如果卡在 resolve说明模块搜索路径有问题如果是 emit多半是文件太大或者插件做了额外操作。还有一个特别容易忽略的点IDE 或者杀毒软件会扫描 node_modules 目录。Windows 上尤其明显Webpack 启动时大量读写 node_modules 里的文件被实时监控拖慢是常有的事。遇到“怎么优化都没用”的情况优先排查这一层。1.2 用打包分析器看清体积构成体积问题比时间问题更好定位因为可以直接看产物。webpack-bundle-analyzer是全行业通用标准Webpack 5 下配合webpack-bundle-analyzer的新版本基本兼容良好直接把分析文件生成到本地然后用浏览器打开。const BundleAnalyzerPlugin require(webpack-bundle-analyzer).BundleAnalyzerPlugin; module.exports { plugins: [ new BundleAnalyzerPlugin({ analyzerMode: static, reportFilename: bundle-report.html, openAnalyzer: false, }), ], };拿到分析报告后重点关注三个东西单个 chunk 的体积峰值、重复打包的模块、vendors chunk 里混入的无关代码。80% 的体积问题都能在这三个维度里找到答案。比如某个模块同时出现在两个业务 chunk 里说明 splitChunks 的配置没生效某个动态 import 的页面 chunk 特别大说明这个页面依赖了不该依赖的公共库vendors chunk 里有巨大的 JSON 数据文件说明某个库的默认导入包含了所有语言包这时候改用 deep import 就能解决。分析报告建议在优化前和优化后各生成一次前后对比才看得出效果。我在实践中习惯把体积数据记录到仓库的 README 或者一个 markdown 文件里每次优化完更新一次作为团队的构建基准线避免后续改崩了没人察觉。2. Webpack 5 的启动提速方案从根上解决 dev 慢诊断清楚之后开始动刀。启动慢这个问题Webpack 5 最大的红利就是内置的持久化缓存。这一节会把开发环境启动慢的核心手段全部过一遍跑完这套配置多数项目的首次构建能压缩到原来的 1/2 到 1/3二次构建基本在一两秒内。2.1 开启 filesystem cache一次性吃满 Webpack 5 红利Webpack 5 之前缓存要靠cache-loader自己搭或者装hard-source-webpack-plugin前者缓存力度有限后者 Webpack 5 完全不兼容我们在升级中踩到的第一个大坑就是它。Webpack 5 内置了cache配置项支持把编译结果缓存到文件系统二次构建时直接走缓存跳过模块解析和 loader 转换。module.exports { cache: { type: filesystem, buildDependencies: { config: [__filename], }, // 默认缓存目录是 node_modules/.cache/webpack cacheDirectory: path.resolve(__dirname, .temp_cache/webpack), }, };buildDependencies这里要解释一下它的作用是让 Webpack 知道“哪些文件的变更会导致缓存失效”。通常把配置文件自己列入其中这样你改了 webpack.config.js缓存会自动作废重新构建。很多人在这个细节上栽跟头以为缓存卡死改不动配置其实就是没配 buildDependencies 或者配置了但没等缓存过期。开启这个配置后二次 dev server 启动速度提升幅度非常大实测一个 200 模块的项目从 15 秒降到 3 秒以内。要注意的是首次构建依然会慢因为没缓存可读所以 CI 环境里如果每次都是全新拉代码缓存收益为零。如果有条件可以考虑把 node_modules 和 .temp_cache 都挂到 CI 的持久化缓存目录里。2.2 loader 层面的提速esbuild-loader 与 swc-loader 的取舍loader 转换是 dev 启动慢的头号嫌疑犯。传统一套babel-loader每次重新构建都要重新跑一遍 Babel 转译遇到大型项目动辄几千个模块时间消耗肉眼可见。Webpack 5 时代有两个替代路线esbuild-loader和swc-loader。esbuild-loader是 esbuild 社区的产物直接调用 esbuild 来做转译和压缩速度相对 babel 有数量级优势实测同一个项目的 TS 转译babel 要 20 秒esbuild 只要 3 秒。swc-loader走的是 Rust 路线性能和 esbuild 相近但 SWC 的生态更贴近 Rust 社区插件机制更丰富。就转译正确性而言两者都高度成熟主流 React/Vue 项目替换都没问题。// 用 esbuild-loader 替换 babel-loader 处理 JS/TS module.exports { module: { rules: [ { test: /\.(js|jsx|ts|tsx)$/, exclude: /node_modules/, use: esbuild-loader, options: { loader: tsx, // 处理 TSX 时用 tsx否则用 ts target: es2015, }, }, ], }, };这里必须提醒一个关键细节esbuild-loader 只能做转译不能做 Babel 的语法 polyfill 和自定义插件逻辑。项目里如果依赖了 Babel 插件比如babel/plugin-transform-runtime、babel-plugin-import这种直接替换就会出现问题。我的建议是如果项目还在持续引入 Babel 插件先保留 babel-loader只对 node_modules 里的第三方包启用 esbuild-loader 的转译或者等验证充分后再全量替换。对于纯 TypeScript 项目esbuild-loader 的价值最大替换成本也最低。另外关于thread-loader多说一句Webpack 5 时代 thread-loader 的作用大幅缩水因为 babel-loader 自身的性能已经有提升esbuild-loader 又在速度上碾压它。thread-loader 开启后项目模块会重新分配增加额外进程调度开销而且和 esbuild-loader 一起用时毫无必要esbuild 内部本身就是并发的。能不碰 thread-loader 就别碰这是我在多个项目里踩完坑后的结论。2.3 resolve 配置少让 Webpack 做无谓的路径探索模块解析阶段Webpack 默认会按照resolve.modules的配置逐层查找 node_modules。如果你的resolve.extensions写得特别多比如后缀数组[.ts, .tsx, .js, .jsx, .json, .vue]那每个 import 语句都要尝试匹配 6 种后缀这个次数一放大性能就下来了。原地优化思路module.exports { resolve: { extensions: [.ts, .tsx, .js, .jsx, .json], // 显式指定模块查找目录避免一层层往上找 modules: [path.resolve(__dirname, node_modules)], // 显式指定入口文件避免默认的 index.js/index.json 猜测 mainFields: [module, main], symlinks: false, }, };mainFields告诉 Webpack 优先使用包的module字段ES Module 版本这样源码在 dev 和构建阶段就能被 tree-shaking 提前剪枝。symlinks: false对 monorepo 项目特别重要如果 node_modules 里的包是软链接默认情况下 Webpack 会去解析链接指向的真实路径加了这个配置后就直接使用构建上下文里的路径能省不少时间。还有一个很多人不知道的细节resolve.alias可以显式映射常用库到指定路径比如把 react 映射到项目里的 react 实际路径避免重复打包或者版本不一致导致的解析时间增长。但 alias 不要滥用过度配置反而会掩盖真实依赖关系。3. 产物体积优化tree-shaking 到代码分割的全链路启动变快了接下来处理“体积大”。这块的核心不是某一条配置而是一整个链条每一环不到位效果都会打折扣。我会从 tree-shaking 讲到代码分割再讲到底什么是真正有效的“按需加载”。3.1 sideEffects: 让 tree-shaking 真正生效很多项目配置了optimization.usedExports以为这样就能自动 tree-shaking 掉没用到的代码。事实上tree-shaking 要真正生效前提是模块本身被标记为无副作用side effect free。如果 package.json 里没写sideEffects: falseWebpack 会保守地保留所有模块顶层的副作用代码——比如给 window 挂属性、修改原型链这些事它不敢动。// 在项目 package.json 里声明 { name: your-project, sideEffects: [ *.css, *.scss, *.less, ./src/polyfills.ts ] }如果你不确定项目里有没有顶层副作用代码从sideEffects: false开始并配合构建后的功能回归测试是最快的路径。如果发现某些模块被误删了症状通常是运行时报错某个变量未定义再把相应文件加进白名单数组。这是标准的渐进式收紧思路。注意CSS 文件必须列入 side effects 白名单否则 Webpack 会认为引入 CSS 是副作用并把它 tree-shake 掉结果是页面样式全丢这坑我踩过不止一次。3.2 splitChunks把公共代码拆到合理粒度Webpack 5 默认的splitChunks配置已经比 4 激进但距“最优”还差得远。我见过很多项目把所有 node_modules 里的库全部打进一个vendorschunk导致这个 chunk 动辄 2MB 以上而且由于它包含所有第三方库缓存策略形同虚设——你升级其中一个库整个 vendors 全部失效。这个设计在实际业务中非常被动。推荐一种更合理的拆分策略module.exports { optimization: { splitChunks: { chunks: all, cacheGroups: { // 核心框架单独一个 chunk react: { test: /[\\/]node_modules[\\/](react|react-dom|react-router)[\\/]/, name: react-vendor, priority: 20, chunks: all, }, // 体积较大的第三方库单独拆分 async-vendor: { test: /[\\/]node_modules[\\/]/, name(module) { const match module.context.match(/[\\/]node_modules[\\/](.*?)([\\/]|$)/); return match ? npm-${match[1].replace(/[_]/g, -)} : unknown; }, minChunks: 1, priority: 10, chunks: all, }, // 业务公共代码 common: { minChunks: 2, priority: 5, name: common, chunks: all, }, }, }, }, };这里priority决定分组命中顺序react 组优先级最高所以 react 相关库会先进 react-vendor剩下的第三方库再进 async-vendor。你用name函数根据模块路径自动生成 chunk 名的方案避免手动维护一个庞大的库名清单。拆出来的 chunk 多了首屏 HTTP 请求数会增加所以拆分的粒度也要看项目网络情况量力而行。我的建议是核心框架一组、大数据量的图表/编辑器库单独一组、其余第三方库按库名拆成小组、业务公共代码一组这样缓存命中率最高更新单个依赖不会导致整个 vendor 缓存失效。3.3 runtimeChunk 与动态 import减少重复代码拆出按需路由runtimeChunk这个配置很多人会忽略但它对长缓存策略至关重要。Webpack 的 runtime 代码里包含了模块映射和 chunk 加载逻辑这部分内容在业务代码变化时往往会更新如果不单独拆出来就可能导致两个相邻 chunk 一起失效。配置很简单module.exports { optimization: { runtimeChunk: { name: (entrypoint) runtime-${entrypoint.name}, }, }, };配合React.lazy和import()做路由级拆包首屏只加载当前路由需要的代码。一个常见的误区是大家以为把页面组件拆出来就算按需加载了但如果页面环境里 import 了一个巨大的全局库被拆出的 chunk 一样会被撑大。真正合理的做法是先通过 bundle analyzer 找到大块在路由层懒加载的同时把大库也做异步拆分。比如图表库 echarts不在入口文件 import而是在使用它的组件里 import这样未使用图表的页面就不会背上 echarts 的体积。另外对图片和字体这类静态资源超过一定阈值会自动以文件形式输出而非 base64 内联。Webpack 5 内置的asset模块替代了旧的 file-loader/url-loader 配置module.exports { module: { rules: [ { test: /\.(png|jpe?g|gif|svg)$/i, type: asset, parser: { dataUrlCondition: { maxSize: 4 * 1024, // 小于 4KB 的图片内联为 base64 }, }, }, ], }, };这里有个细节值得注意作者容易把 base64 阈值调大比如 50KB以此减少请求数但这个度一旦失控首屏 HTML 里会嵌入几十个超大字符串阻塞解析。一般项目控制在 4~10KB 之间比较合理。上面这段配置同时建议配合 svg 的优化插件使用因为他们本质处理的是不同对象asset 内联是编码问题SVG 压缩减小的是资源本身的体积。3.4 CSS 压缩提取与 HTML 层面的体积精简CSS 体积经常被忽略其实代码分块时 CSS 跟着 chunk 走压缩率如果没用好页面加载会很亏。推荐mini-css-extract-plugin提取单独 CSS 文件配合css-minimizer-webpack-plugin压缩const MiniCssExtractPlugin require(mini-css-extract-plugin); const CssMinimizerPlugin require(css-minimizer-webpack-plugin); module.exports { module: { rules: [ { test: /\.css$/, use: [MiniCssExtractPlugin.loader, css-loader], }, ], }, plugins: [ new MiniCssExtractPlugin({ filename: css/[name].[contenthash:8].css, chunkFilename: css/[name].[contenthash:8].chunk.css, }), ], optimization: { minimizer: [ new CssMinimizerPlugin(), ], }, };[contenthash:8]这种命名策略一定要用起来它是长缓存的核心。文件内容变了 hash 才变没变的文件指纹不变这样浏览器能继续用缓存。就我自己测试的效果来看CSS 压缩加 hash 命名后后续发布带来的缓存失效范围显著缩小页面二次访问速度提升非常明显。HTML 层面html-webpack-plugin是标配但很多人没配置它的模板压缩。记住加上minify选项默认的模板中大量注释和空格都会被移除。虽然这部分体积按 KB 计不算最大头但配合 content hash 和 cache 策略能让产物看起来干净利落。3.5 外部化大库CDN 与 DllPlugin 的边界思考看到大库本能反应是扔 CDN 用 script 标签引入省去打包时间同时减小产物体积。但外部化的代价是 HTTP 连接和缓存管理转移到外部资源。公共 CDN 的稳定性、版本同步、年会出问题都很难受。这个方案适合极稳定的依赖比如 react、react-dom、vue版本升级频率低公共 CDN 都能命中高不适合自定义 UI 库、业务组件库、内部私有 npm 包。DllPlugin动态链接库在 Webpack 4 时代是优化 dev 启动的标配但Webpack 5 有了 filesystem cache 之后DllPlugin 的边际收益已经降低到几乎没有属于被时代淘汰的方案。现在再维护一份 DLL 打包配置只是增加心智负担新项目不要走这条旧路。4. 插件与模式选择的实战经验按需开启别让插件拖累构建这一节的说法可能和很多人的直觉相反插件越多构建不一定越慢但插件配置越随意构建变慢的概率越大。尤其是在 Webpack 5 里很多 Webpack 4 时代的“标配”插件已经成了性能陷阱。4.1 开发模式与生产模式的配置拆分不少人用一个巨型的 webpack.config.js 同时覆盖 dev 和 prod所有插件、source-map、minimizer 全部混在里面结果就是 dev server 也要跑 compression-webpack-plugin、要做代码压缩速度自然慢得离谱。正确做法是拆三份配置webpack.common.js公共部分比如 entry、module.rules、resolvewebpack.dev.jsdev server、devtool用eval-cheap-module-source-map千万别用source-mapwebpack.prod.js代码压缩、contenthash、tree-shaking、CDN 转换// webpack.dev.js const { merge } require(webpack-merge); const common require(./webpack.common.js); module.exports merge(common, { mode: development, devtool: eval-cheap-module-source-map, devServer: { hot: true, historyApiFallback: true, port: 8080, }, });source-map模式在 dev 环境下会生成完整的原始映射文件文件数量多、生成慢完全没必要。eval-cheap-module-source-map在保证报错定位到源码的同时生成速度快一截。不缺精细度的话甚至可以直接用eval报错定位到编译后代码对一般项目够用了。生产模式的 minification 配置如果用了 esbuild-loader 或者 swc-loader压缩可以直接复用这两个工具内置的压缩能力比terser-webpack-plugin快不是一点半点// webpack.prod.js module.exports merge(common, { mode: production, optimization: { minimize: true, minimizer: [ // 使用 esbuild 做压缩 new EsbuildPlugin({ target: es2015 }), new CssMinimizerPlugin(), ], }, });用 esbuild 压缩要注意一个兼容性细节esbuild 的压缩逻辑不会像 terser 那样做完整的 ECMAScript 语法降级所以如果你的目标浏览器很老比如 IE11就不能用 esbuild 压缩只能退回 terser。现在前端项目基本都抛弃 IE11 了这个限制影响不大但必须心里有数。4.2 按需加载与动态 polyfill 的真实收益体积优化的另一个思路是“减少要做的事情”。Webpack 5 的optimization.moduleIds与chunkIds在开发模式和生产模式有不同的默认值这会直接影响 hash 稳定性。建议显式设置module.exports { optimization: { chunkIds: deterministic, moduleIds: deterministic, }, };deterministic模式下模块的 ID 是根据模块路径计算的模块不变 ID 就不变。如果你不设置dev 环境默认用named生产环境默认用deterministic但为了统一行为显式配置最保险。这个配置对长期迭代的项目格外重要——它能保证代码增量更新时没有变更的模块 hash 不变浏览器能最大化利用缓存。动态 polyfill 这块我的经验是现代浏览器根本不需要把整个core-js全量引入。以往 write 老的 babel-polyfill 用法会把几百 KB polyfill 直接塞进入口。现在推荐三个步骤只保留真正需要的 core-js polyfill 条目用 browserslist 控制目标浏览器必要时用 polyfill-service 动态下发。把这三步做完产物体积能减少不少而且还不会出现老浏览器白屏。5. 持久化缓存与 CI/CD 的联动实践前面提到 filesystem cache 在 CI 里收益有限但这是可以解决的。很多团队在 CI 上每次构建都是全新环境node_modules 也重新安装缓存自然没有作用。要榨干 Webpack 5 的缓存能力需要在 CI/CD 体系里配合起来。5.1 GitHub Actions/GitLab CI 的缓存配置示例以 GitHub Actions 为例- name: Cache node_modules uses: actions/cachev3 with: path: | node_modules .temp_cache/webpack key: ${{ runner.os }}-webpack-${{ hashFiles(**/package-lock.json) }} - name: Install dependencies run: npm ci - name: Build run: npm run build在 GitLab CI 里对应的是 cache 关键字把node_modules和 webpack 的 cacheDirectory 都放进 cache path。这样每次流水线只要 package-lock 没变就能直接从缓存文件构建整个流水线时间可以压缩到原来的一半甚至更少。但要注意缓存大了之后超过几百 MB缓存的拉取和上传本身也会耗时收益会递减。所以 cacheDirectory 建议只放 Webpack 缓存不要把整个.cache目录都塞进去。还有一点容易被忽略CI 上要保证 Webpack 缓存路径的一致性。有些流水线会在构建命令前执行rm -rf清理旧目录如果没把 cacheDirectory 纳入保留清单前面配置的缓存全部白搭。建议在 package.json scripts 里统一命令由构建脚本保证目录存在{ scripts: { build: rimraf dist webpack --config webpack.prod.js, prebuild: mkdir -p .temp_cache/webpack } }5.2 缓存失效与版本升级的排查套路Webpack 5 的 filesystem cache 偶尔会让升级依赖后构建配置变成“老版本外壳”表现是某个库的新特性在构建里无效。遇到这种问题先别怀疑 Webpack直接删掉.temp_cache/webpack目录重跑一次。如果重跑后正常基本可以确认是缓存没正确失效。预防办法是像前面说的把buildDependencies配置全同时注意Webpack 自身版本升级时缓存目录的标记会变跨小版本升级后建议强制清理一次。这一点在团队里最好写进升级文档免得有人踩坑后不知道原因是缓存。另外cache.version配置项也可以留一手。如果你们有特殊场景需要手动让缓存整体失效比如做了大规模依赖升级可以临时改一下 version 字段Webpack 会自动切换新的缓存目录相当于无痛重建缓存module.exports { cache: { type: filesystem, version: 0.1.2, // 升级到 0.2.0 时自动启用新的缓存空间 }, };6. 常见问题与排查技巧实录最后一部分把我印象最深、在多个项目里反复出现的坑集中记录成表大家遇到类似症状直接翻阅对照。表格是整理这类信息最直观的形式比长篇描述好用得多。6.1 高频坑速查表症状常见原因排查思路解决方案dev 首次构建慢大量模块 未开启 filesystem cache检查 cache 配置开启cache: { type: filesystem }dev 二次构建仍然慢loader 转换逻辑过重看模块耗时 profiler换成 esbuild-loader/swc-loader修改配置文件后行为不变buildDependencies 未配置检查 cache 是否命中添加buildDependencies.config产物体积大但找不到大块分析报告反而看不到大 chunk确认是否被 CSS 污染提取 CSS 压缩重新分析动态 import 的路由体积巨大页面里同步导入了大库用 analyzer 看 chunk dependency组件内异步引用大库更新单个依赖导致全部缓存失效splitChunks 把第三方库打包到一个 chunk看 vendors chunk 构成按库名拆分 chunk设置 hash升级 Webpack 5 后有插件冲突Webpack 4 时代的插件不兼容控制台报错定位插件删除/替换为官方或社区维护版本source-map 生成极慢devtool 用了source-map检查 devtool 配置使用eval-cheap-module-source-map图片全部变成 base64 导致 HTML 巨大dataUrlCondition maxSize 设置过大看 HTML 里的 data 串调小 maxSize控制在 4~10KB生产构建后样式丢失sideEffects 白名单漏掉 CSS检查构建产物的 CSS 文件在 sideEffects 数组中加入*.cssCI 里构建缓存一直不生效CI 环境没有缓存目录持久化检查 CI 缓存配置配置 node_modules 与 cacheDirectory 的缓存策略使用 esbuild-loader 后某个库报错库依赖了 Babel 插件特性看报错是否在特定库内对该库单独保留 babel-loader6.2 一个实际案例的排查过程顺手分享一个真实案例某项目升级 Webpack 5 后dev server 启动从 12 秒变成 35 秒。所有人都认为是缓存问题但调试发现cache: { type: filesystem }已开启还是慢。后来在 profiler 里看到node_modules/antd/lib/index.js模块的解析耗时奇高进一步检查发现resolve.alias里把 antd 指向了antd/es目录而 antd/es 下的组件模块数量多达上千个ESM 版本的解析路径更多导致搜索时间暴涨。最后把 alias 去掉改用 Webpack 5 的mainFields: [module, main]让 antd 自动走 ESM 格式启动时间回到 10 秒以内。这个案例的启示就是性能问题往往是你为了省事加上的配置导致的排查时要把所有自定义配置过一遍而不是只盯着“优化手段”。还有一次线上环境的 CSS 样式错位排查了很久发现是sideEffects数组里写了*.css但项目里又有一处例外某个全局样式文件内部 import 了字体文件字体文件被当成副作用一并摇掉。这类 edge case 不能靠背配置解决只能靠回归测试兜底。所以我后来养成了一个习惯每次调完构建配置先跑一遍核心路由的冒烟测试哪怕只是一个简单的页面渲染检查也能拦截掉大多数 tree-shaking 误删事件。7. 后续还能往哪个方向扩展构建优化这件事没有终点Webpack 5 这波改造完成之后如果还想继续压榨构建效率和产物体积可以考虑这几个方向升级到 Vite 或者 Rspack 这类新一代构建工具它们确实是更快的方案但前期迁移成本和生态兼容成本都不低接入 Module Federation让多个应用共享运行时依赖从架构层面减少重复打包做 import 的 cost 分析团队里加一条构建检查规则超过指定体积的模块 import 给出 warning 甚至阻断把体积控制从“事后优化”变成“事前预防”。我个人在实际操作中的体会是构建优化更像是一次体系治理而不是某条配置的魔法。你改掉一个 loader存储缓存策略调整拆一个 chunk每个环节单独看效果都不算惊人但它们叠加起来就是几十秒到几秒、几 MB 到几百 KB 的差距。真正难的不是配置本身而是根据项目特性做出取舍以及每次改完都确保线上功能没有受到影响。工具一直在变但“先测量、再优化、后回归”这套方法论是永不过时的。最后分享一个小技巧在 package.json 的 build 脚本里加一条--json compile-stats.json输出每次构建完自动保存编译数据时间久了就是一份真实可信的优化成果记录。团队复盘、向领导汇报、新人接手排查性能问题这份数据比任何口头描述都管用。 Webpack 5 构建优化实战：从启动提速到产物体积瘦身
没经历过 Webpack 构建时间从 40 秒降到 3 秒、产物体积从 2MB 减到 800KB 的过程你很难对“构建优化”这件事有实感。Webpack 5 发布已经有段时间了但大部分项目其实还停留在“能用就行”的状态每次 npm run dev 都要等半天vite 用户茶余饭后的笑柄线上包越打越大首屏加载越来越慢领导问起来只能支支吾吾。这标题看着像要聊原理其实核心就两件事启动慢怎么治、体积大怎么减。这篇内容不整虚的我把实战里用得上的方案、配置、踩过的坑分门别类整理出来按步骤抄就能见效特别适合手里正维护 Webpack 项目、想升级到 Webpack 5 或者已经在 Webpack 5 里挣扎的团队参考。这篇博文很长但我保证没有一个字是凑数的。先从“为什么会慢、为什么会大”开始说起因为不搞清楚病根后面所有优化手段你都不知道为什么有效、哪些是白费力气。诊断有问题优化就是无头苍蝇。1. 先搞清楚你的项目到底慢在哪、大在哪很多人一上来就调配置结果折腾半天效果微乎其微问题就出在没做诊断。Webpack 构建慢和产物体积大的原因往往不止一个而且不同规模的项目瓶颈位置完全不同。我见过一个项目dev server 启动要 50 秒所有人以为是 loader 太慢结果一查是某个第三方库被错误地打进了依赖解析链路还有项目体积 90% 来自一个几乎用不到的图表库只是因为在入口文件里被默认导入了。不测量就优化等于蒙眼开车。1.1 用计时工具定位构建瓶颈Webpack 5 里做构建耗时分析的常见工具是speed-measure-webpack-plugin但这个插件和 Webpack 5 的兼容存在一些已知问题部分场景下会报错或者统计不出结果。我更推荐直接利用 Webpack 内置能力在webpack.config.js里临时包一层计时逻辑配合stats配置输出详细的耗时数据。// 临时调试脚本measure-build.js const { webpack } require(webpack); const config require(./webpack.config.js); webpack(config, (err, stats) { if (err || stats.hasErrors()) { console.error(err || stats.toString(errors-only)); return; } // 输出关键耗时指标 const info stats.toJson({ timings: true, modules: true, chunks: true, reasons: false, }); console.log(总耗时: ${info.time}ms); console.log(总模块数: ${info.modules.length}); console.log(总块数: ${info.chunks.length}); // 按耗时排序找出最慢的模块 info.modules .filter((m) m.profile m.profile.duration 1000) .sort((a, b) b.profile.duration - a.profile.duration) .slice(0, 20) .forEach((m) { console.log(${(m.profile.duration / 1000).toFixed(2)}s, m.name); }); });更直接的做法是启动 dev server 时加上--profile --json把输出的 JSON 扔进webpack --analyse可视化页面里看。但在实际操作里最朴素的方式反而是最有用的盯着终端输出看 Webpack 在哪个阶段卡住。编译过程分为resolve解析模块路径、loaders转换文件、pack生成代码、emit输出文件四个主要阶段。如果卡在 loaders说明 loader 处理慢如果卡在 resolve说明模块搜索路径有问题如果是 emit多半是文件太大或者插件做了额外操作。还有一个特别容易忽略的点IDE 或者杀毒软件会扫描 node_modules 目录。Windows 上尤其明显Webpack 启动时大量读写 node_modules 里的文件被实时监控拖慢是常有的事。遇到“怎么优化都没用”的情况优先排查这一层。1.2 用打包分析器看清体积构成体积问题比时间问题更好定位因为可以直接看产物。webpack-bundle-analyzer是全行业通用标准Webpack 5 下配合webpack-bundle-analyzer的新版本基本兼容良好直接把分析文件生成到本地然后用浏览器打开。const BundleAnalyzerPlugin require(webpack-bundle-analyzer).BundleAnalyzerPlugin; module.exports { plugins: [ new BundleAnalyzerPlugin({ analyzerMode: static, reportFilename: bundle-report.html, openAnalyzer: false, }), ], };拿到分析报告后重点关注三个东西单个 chunk 的体积峰值、重复打包的模块、vendors chunk 里混入的无关代码。80% 的体积问题都能在这三个维度里找到答案。比如某个模块同时出现在两个业务 chunk 里说明 splitChunks 的配置没生效某个动态 import 的页面 chunk 特别大说明这个页面依赖了不该依赖的公共库vendors chunk 里有巨大的 JSON 数据文件说明某个库的默认导入包含了所有语言包这时候改用 deep import 就能解决。分析报告建议在优化前和优化后各生成一次前后对比才看得出效果。我在实践中习惯把体积数据记录到仓库的 README 或者一个 markdown 文件里每次优化完更新一次作为团队的构建基准线避免后续改崩了没人察觉。2. Webpack 5 的启动提速方案从根上解决 dev 慢诊断清楚之后开始动刀。启动慢这个问题Webpack 5 最大的红利就是内置的持久化缓存。这一节会把开发环境启动慢的核心手段全部过一遍跑完这套配置多数项目的首次构建能压缩到原来的 1/2 到 1/3二次构建基本在一两秒内。2.1 开启 filesystem cache一次性吃满 Webpack 5 红利Webpack 5 之前缓存要靠cache-loader自己搭或者装hard-source-webpack-plugin前者缓存力度有限后者 Webpack 5 完全不兼容我们在升级中踩到的第一个大坑就是它。Webpack 5 内置了cache配置项支持把编译结果缓存到文件系统二次构建时直接走缓存跳过模块解析和 loader 转换。module.exports { cache: { type: filesystem, buildDependencies: { config: [__filename], }, // 默认缓存目录是 node_modules/.cache/webpack cacheDirectory: path.resolve(__dirname, .temp_cache/webpack), }, };buildDependencies这里要解释一下它的作用是让 Webpack 知道“哪些文件的变更会导致缓存失效”。通常把配置文件自己列入其中这样你改了 webpack.config.js缓存会自动作废重新构建。很多人在这个细节上栽跟头以为缓存卡死改不动配置其实就是没配 buildDependencies 或者配置了但没等缓存过期。开启这个配置后二次 dev server 启动速度提升幅度非常大实测一个 200 模块的项目从 15 秒降到 3 秒以内。要注意的是首次构建依然会慢因为没缓存可读所以 CI 环境里如果每次都是全新拉代码缓存收益为零。如果有条件可以考虑把 node_modules 和 .temp_cache 都挂到 CI 的持久化缓存目录里。2.2 loader 层面的提速esbuild-loader 与 swc-loader 的取舍loader 转换是 dev 启动慢的头号嫌疑犯。传统一套babel-loader每次重新构建都要重新跑一遍 Babel 转译遇到大型项目动辄几千个模块时间消耗肉眼可见。Webpack 5 时代有两个替代路线esbuild-loader和swc-loader。esbuild-loader是 esbuild 社区的产物直接调用 esbuild 来做转译和压缩速度相对 babel 有数量级优势实测同一个项目的 TS 转译babel 要 20 秒esbuild 只要 3 秒。swc-loader走的是 Rust 路线性能和 esbuild 相近但 SWC 的生态更贴近 Rust 社区插件机制更丰富。就转译正确性而言两者都高度成熟主流 React/Vue 项目替换都没问题。// 用 esbuild-loader 替换 babel-loader 处理 JS/TS module.exports { module: { rules: [ { test: /\.(js|jsx|ts|tsx)$/, exclude: /node_modules/, use: esbuild-loader, options: { loader: tsx, // 处理 TSX 时用 tsx否则用 ts target: es2015, }, }, ], }, };这里必须提醒一个关键细节esbuild-loader 只能做转译不能做 Babel 的语法 polyfill 和自定义插件逻辑。项目里如果依赖了 Babel 插件比如babel/plugin-transform-runtime、babel-plugin-import这种直接替换就会出现问题。我的建议是如果项目还在持续引入 Babel 插件先保留 babel-loader只对 node_modules 里的第三方包启用 esbuild-loader 的转译或者等验证充分后再全量替换。对于纯 TypeScript 项目esbuild-loader 的价值最大替换成本也最低。另外关于thread-loader多说一句Webpack 5 时代 thread-loader 的作用大幅缩水因为 babel-loader 自身的性能已经有提升esbuild-loader 又在速度上碾压它。thread-loader 开启后项目模块会重新分配增加额外进程调度开销而且和 esbuild-loader 一起用时毫无必要esbuild 内部本身就是并发的。能不碰 thread-loader 就别碰这是我在多个项目里踩完坑后的结论。2.3 resolve 配置少让 Webpack 做无谓的路径探索模块解析阶段Webpack 默认会按照resolve.modules的配置逐层查找 node_modules。如果你的resolve.extensions写得特别多比如后缀数组[.ts, .tsx, .js, .jsx, .json, .vue]那每个 import 语句都要尝试匹配 6 种后缀这个次数一放大性能就下来了。原地优化思路module.exports { resolve: { extensions: [.ts, .tsx, .js, .jsx, .json], // 显式指定模块查找目录避免一层层往上找 modules: [path.resolve(__dirname, node_modules)], // 显式指定入口文件避免默认的 index.js/index.json 猜测 mainFields: [module, main], symlinks: false, }, };mainFields告诉 Webpack 优先使用包的module字段ES Module 版本这样源码在 dev 和构建阶段就能被 tree-shaking 提前剪枝。symlinks: false对 monorepo 项目特别重要如果 node_modules 里的包是软链接默认情况下 Webpack 会去解析链接指向的真实路径加了这个配置后就直接使用构建上下文里的路径能省不少时间。还有一个很多人不知道的细节resolve.alias可以显式映射常用库到指定路径比如把 react 映射到项目里的 react 实际路径避免重复打包或者版本不一致导致的解析时间增长。但 alias 不要滥用过度配置反而会掩盖真实依赖关系。3. 产物体积优化tree-shaking 到代码分割的全链路启动变快了接下来处理“体积大”。这块的核心不是某一条配置而是一整个链条每一环不到位效果都会打折扣。我会从 tree-shaking 讲到代码分割再讲到底什么是真正有效的“按需加载”。3.1 sideEffects: 让 tree-shaking 真正生效很多项目配置了optimization.usedExports以为这样就能自动 tree-shaking 掉没用到的代码。事实上tree-shaking 要真正生效前提是模块本身被标记为无副作用side effect free。如果 package.json 里没写sideEffects: falseWebpack 会保守地保留所有模块顶层的副作用代码——比如给 window 挂属性、修改原型链这些事它不敢动。// 在项目 package.json 里声明 { name: your-project, sideEffects: [ *.css, *.scss, *.less, ./src/polyfills.ts ] }如果你不确定项目里有没有顶层副作用代码从sideEffects: false开始并配合构建后的功能回归测试是最快的路径。如果发现某些模块被误删了症状通常是运行时报错某个变量未定义再把相应文件加进白名单数组。这是标准的渐进式收紧思路。注意CSS 文件必须列入 side effects 白名单否则 Webpack 会认为引入 CSS 是副作用并把它 tree-shake 掉结果是页面样式全丢这坑我踩过不止一次。3.2 splitChunks把公共代码拆到合理粒度Webpack 5 默认的splitChunks配置已经比 4 激进但距“最优”还差得远。我见过很多项目把所有 node_modules 里的库全部打进一个vendorschunk导致这个 chunk 动辄 2MB 以上而且由于它包含所有第三方库缓存策略形同虚设——你升级其中一个库整个 vendors 全部失效。这个设计在实际业务中非常被动。推荐一种更合理的拆分策略module.exports { optimization: { splitChunks: { chunks: all, cacheGroups: { // 核心框架单独一个 chunk react: { test: /[\\/]node_modules[\\/](react|react-dom|react-router)[\\/]/, name: react-vendor, priority: 20, chunks: all, }, // 体积较大的第三方库单独拆分 async-vendor: { test: /[\\/]node_modules[\\/]/, name(module) { const match module.context.match(/[\\/]node_modules[\\/](.*?)([\\/]|$)/); return match ? npm-${match[1].replace(/[_]/g, -)} : unknown; }, minChunks: 1, priority: 10, chunks: all, }, // 业务公共代码 common: { minChunks: 2, priority: 5, name: common, chunks: all, }, }, }, }, };这里priority决定分组命中顺序react 组优先级最高所以 react 相关库会先进 react-vendor剩下的第三方库再进 async-vendor。你用name函数根据模块路径自动生成 chunk 名的方案避免手动维护一个庞大的库名清单。拆出来的 chunk 多了首屏 HTTP 请求数会增加所以拆分的粒度也要看项目网络情况量力而行。我的建议是核心框架一组、大数据量的图表/编辑器库单独一组、其余第三方库按库名拆成小组、业务公共代码一组这样缓存命中率最高更新单个依赖不会导致整个 vendor 缓存失效。3.3 runtimeChunk 与动态 import减少重复代码拆出按需路由runtimeChunk这个配置很多人会忽略但它对长缓存策略至关重要。Webpack 的 runtime 代码里包含了模块映射和 chunk 加载逻辑这部分内容在业务代码变化时往往会更新如果不单独拆出来就可能导致两个相邻 chunk 一起失效。配置很简单module.exports { optimization: { runtimeChunk: { name: (entrypoint) runtime-${entrypoint.name}, }, }, };配合React.lazy和import()做路由级拆包首屏只加载当前路由需要的代码。一个常见的误区是大家以为把页面组件拆出来就算按需加载了但如果页面环境里 import 了一个巨大的全局库被拆出的 chunk 一样会被撑大。真正合理的做法是先通过 bundle analyzer 找到大块在路由层懒加载的同时把大库也做异步拆分。比如图表库 echarts不在入口文件 import而是在使用它的组件里 import这样未使用图表的页面就不会背上 echarts 的体积。另外对图片和字体这类静态资源超过一定阈值会自动以文件形式输出而非 base64 内联。Webpack 5 内置的asset模块替代了旧的 file-loader/url-loader 配置module.exports { module: { rules: [ { test: /\.(png|jpe?g|gif|svg)$/i, type: asset, parser: { dataUrlCondition: { maxSize: 4 * 1024, // 小于 4KB 的图片内联为 base64 }, }, }, ], }, };这里有个细节值得注意作者容易把 base64 阈值调大比如 50KB以此减少请求数但这个度一旦失控首屏 HTML 里会嵌入几十个超大字符串阻塞解析。一般项目控制在 4~10KB 之间比较合理。上面这段配置同时建议配合 svg 的优化插件使用因为他们本质处理的是不同对象asset 内联是编码问题SVG 压缩减小的是资源本身的体积。3.4 CSS 压缩提取与 HTML 层面的体积精简CSS 体积经常被忽略其实代码分块时 CSS 跟着 chunk 走压缩率如果没用好页面加载会很亏。推荐mini-css-extract-plugin提取单独 CSS 文件配合css-minimizer-webpack-plugin压缩const MiniCssExtractPlugin require(mini-css-extract-plugin); const CssMinimizerPlugin require(css-minimizer-webpack-plugin); module.exports { module: { rules: [ { test: /\.css$/, use: [MiniCssExtractPlugin.loader, css-loader], }, ], }, plugins: [ new MiniCssExtractPlugin({ filename: css/[name].[contenthash:8].css, chunkFilename: css/[name].[contenthash:8].chunk.css, }), ], optimization: { minimizer: [ new CssMinimizerPlugin(), ], }, };[contenthash:8]这种命名策略一定要用起来它是长缓存的核心。文件内容变了 hash 才变没变的文件指纹不变这样浏览器能继续用缓存。就我自己测试的效果来看CSS 压缩加 hash 命名后后续发布带来的缓存失效范围显著缩小页面二次访问速度提升非常明显。HTML 层面html-webpack-plugin是标配但很多人没配置它的模板压缩。记住加上minify选项默认的模板中大量注释和空格都会被移除。虽然这部分体积按 KB 计不算最大头但配合 content hash 和 cache 策略能让产物看起来干净利落。3.5 外部化大库CDN 与 DllPlugin 的边界思考看到大库本能反应是扔 CDN 用 script 标签引入省去打包时间同时减小产物体积。但外部化的代价是 HTTP 连接和缓存管理转移到外部资源。公共 CDN 的稳定性、版本同步、年会出问题都很难受。这个方案适合极稳定的依赖比如 react、react-dom、vue版本升级频率低公共 CDN 都能命中高不适合自定义 UI 库、业务组件库、内部私有 npm 包。DllPlugin动态链接库在 Webpack 4 时代是优化 dev 启动的标配但Webpack 5 有了 filesystem cache 之后DllPlugin 的边际收益已经降低到几乎没有属于被时代淘汰的方案。现在再维护一份 DLL 打包配置只是增加心智负担新项目不要走这条旧路。4. 插件与模式选择的实战经验按需开启别让插件拖累构建这一节的说法可能和很多人的直觉相反插件越多构建不一定越慢但插件配置越随意构建变慢的概率越大。尤其是在 Webpack 5 里很多 Webpack 4 时代的“标配”插件已经成了性能陷阱。4.1 开发模式与生产模式的配置拆分不少人用一个巨型的 webpack.config.js 同时覆盖 dev 和 prod所有插件、source-map、minimizer 全部混在里面结果就是 dev server 也要跑 compression-webpack-plugin、要做代码压缩速度自然慢得离谱。正确做法是拆三份配置webpack.common.js公共部分比如 entry、module.rules、resolvewebpack.dev.jsdev server、devtool用eval-cheap-module-source-map千万别用source-mapwebpack.prod.js代码压缩、contenthash、tree-shaking、CDN 转换// webpack.dev.js const { merge } require(webpack-merge); const common require(./webpack.common.js); module.exports merge(common, { mode: development, devtool: eval-cheap-module-source-map, devServer: { hot: true, historyApiFallback: true, port: 8080, }, });source-map模式在 dev 环境下会生成完整的原始映射文件文件数量多、生成慢完全没必要。eval-cheap-module-source-map在保证报错定位到源码的同时生成速度快一截。不缺精细度的话甚至可以直接用eval报错定位到编译后代码对一般项目够用了。生产模式的 minification 配置如果用了 esbuild-loader 或者 swc-loader压缩可以直接复用这两个工具内置的压缩能力比terser-webpack-plugin快不是一点半点// webpack.prod.js module.exports merge(common, { mode: production, optimization: { minimize: true, minimizer: [ // 使用 esbuild 做压缩 new EsbuildPlugin({ target: es2015 }), new CssMinimizerPlugin(), ], }, });用 esbuild 压缩要注意一个兼容性细节esbuild 的压缩逻辑不会像 terser 那样做完整的 ECMAScript 语法降级所以如果你的目标浏览器很老比如 IE11就不能用 esbuild 压缩只能退回 terser。现在前端项目基本都抛弃 IE11 了这个限制影响不大但必须心里有数。4.2 按需加载与动态 polyfill 的真实收益体积优化的另一个思路是“减少要做的事情”。Webpack 5 的optimization.moduleIds与chunkIds在开发模式和生产模式有不同的默认值这会直接影响 hash 稳定性。建议显式设置module.exports { optimization: { chunkIds: deterministic, moduleIds: deterministic, }, };deterministic模式下模块的 ID 是根据模块路径计算的模块不变 ID 就不变。如果你不设置dev 环境默认用named生产环境默认用deterministic但为了统一行为显式配置最保险。这个配置对长期迭代的项目格外重要——它能保证代码增量更新时没有变更的模块 hash 不变浏览器能最大化利用缓存。动态 polyfill 这块我的经验是现代浏览器根本不需要把整个core-js全量引入。以往 write 老的 babel-polyfill 用法会把几百 KB polyfill 直接塞进入口。现在推荐三个步骤只保留真正需要的 core-js polyfill 条目用 browserslist 控制目标浏览器必要时用 polyfill-service 动态下发。把这三步做完产物体积能减少不少而且还不会出现老浏览器白屏。5. 持久化缓存与 CI/CD 的联动实践前面提到 filesystem cache 在 CI 里收益有限但这是可以解决的。很多团队在 CI 上每次构建都是全新环境node_modules 也重新安装缓存自然没有作用。要榨干 Webpack 5 的缓存能力需要在 CI/CD 体系里配合起来。5.1 GitHub Actions/GitLab CI 的缓存配置示例以 GitHub Actions 为例- name: Cache node_modules uses: actions/cachev3 with: path: | node_modules .temp_cache/webpack key: ${{ runner.os }}-webpack-${{ hashFiles(**/package-lock.json) }} - name: Install dependencies run: npm ci - name: Build run: npm run build在 GitLab CI 里对应的是 cache 关键字把node_modules和 webpack 的 cacheDirectory 都放进 cache path。这样每次流水线只要 package-lock 没变就能直接从缓存文件构建整个流水线时间可以压缩到原来的一半甚至更少。但要注意缓存大了之后超过几百 MB缓存的拉取和上传本身也会耗时收益会递减。所以 cacheDirectory 建议只放 Webpack 缓存不要把整个.cache目录都塞进去。还有一点容易被忽略CI 上要保证 Webpack 缓存路径的一致性。有些流水线会在构建命令前执行rm -rf清理旧目录如果没把 cacheDirectory 纳入保留清单前面配置的缓存全部白搭。建议在 package.json scripts 里统一命令由构建脚本保证目录存在{ scripts: { build: rimraf dist webpack --config webpack.prod.js, prebuild: mkdir -p .temp_cache/webpack } }5.2 缓存失效与版本升级的排查套路Webpack 5 的 filesystem cache 偶尔会让升级依赖后构建配置变成“老版本外壳”表现是某个库的新特性在构建里无效。遇到这种问题先别怀疑 Webpack直接删掉.temp_cache/webpack目录重跑一次。如果重跑后正常基本可以确认是缓存没正确失效。预防办法是像前面说的把buildDependencies配置全同时注意Webpack 自身版本升级时缓存目录的标记会变跨小版本升级后建议强制清理一次。这一点在团队里最好写进升级文档免得有人踩坑后不知道原因是缓存。另外cache.version配置项也可以留一手。如果你们有特殊场景需要手动让缓存整体失效比如做了大规模依赖升级可以临时改一下 version 字段Webpack 会自动切换新的缓存目录相当于无痛重建缓存module.exports { cache: { type: filesystem, version: 0.1.2, // 升级到 0.2.0 时自动启用新的缓存空间 }, };6. 常见问题与排查技巧实录最后一部分把我印象最深、在多个项目里反复出现的坑集中记录成表大家遇到类似症状直接翻阅对照。表格是整理这类信息最直观的形式比长篇描述好用得多。6.1 高频坑速查表症状常见原因排查思路解决方案dev 首次构建慢大量模块 未开启 filesystem cache检查 cache 配置开启cache: { type: filesystem }dev 二次构建仍然慢loader 转换逻辑过重看模块耗时 profiler换成 esbuild-loader/swc-loader修改配置文件后行为不变buildDependencies 未配置检查 cache 是否命中添加buildDependencies.config产物体积大但找不到大块分析报告反而看不到大 chunk确认是否被 CSS 污染提取 CSS 压缩重新分析动态 import 的路由体积巨大页面里同步导入了大库用 analyzer 看 chunk dependency组件内异步引用大库更新单个依赖导致全部缓存失效splitChunks 把第三方库打包到一个 chunk看 vendors chunk 构成按库名拆分 chunk设置 hash升级 Webpack 5 后有插件冲突Webpack 4 时代的插件不兼容控制台报错定位插件删除/替换为官方或社区维护版本source-map 生成极慢devtool 用了source-map检查 devtool 配置使用eval-cheap-module-source-map图片全部变成 base64 导致 HTML 巨大dataUrlCondition maxSize 设置过大看 HTML 里的 data 串调小 maxSize控制在 4~10KB生产构建后样式丢失sideEffects 白名单漏掉 CSS检查构建产物的 CSS 文件在 sideEffects 数组中加入*.cssCI 里构建缓存一直不生效CI 环境没有缓存目录持久化检查 CI 缓存配置配置 node_modules 与 cacheDirectory 的缓存策略使用 esbuild-loader 后某个库报错库依赖了 Babel 插件特性看报错是否在特定库内对该库单独保留 babel-loader6.2 一个实际案例的排查过程顺手分享一个真实案例某项目升级 Webpack 5 后dev server 启动从 12 秒变成 35 秒。所有人都认为是缓存问题但调试发现cache: { type: filesystem }已开启还是慢。后来在 profiler 里看到node_modules/antd/lib/index.js模块的解析耗时奇高进一步检查发现resolve.alias里把 antd 指向了antd/es目录而 antd/es 下的组件模块数量多达上千个ESM 版本的解析路径更多导致搜索时间暴涨。最后把 alias 去掉改用 Webpack 5 的mainFields: [module, main]让 antd 自动走 ESM 格式启动时间回到 10 秒以内。这个案例的启示就是性能问题往往是你为了省事加上的配置导致的排查时要把所有自定义配置过一遍而不是只盯着“优化手段”。还有一次线上环境的 CSS 样式错位排查了很久发现是sideEffects数组里写了*.css但项目里又有一处例外某个全局样式文件内部 import 了字体文件字体文件被当成副作用一并摇掉。这类 edge case 不能靠背配置解决只能靠回归测试兜底。所以我后来养成了一个习惯每次调完构建配置先跑一遍核心路由的冒烟测试哪怕只是一个简单的页面渲染检查也能拦截掉大多数 tree-shaking 误删事件。7. 后续还能往哪个方向扩展构建优化这件事没有终点Webpack 5 这波改造完成之后如果还想继续压榨构建效率和产物体积可以考虑这几个方向升级到 Vite 或者 Rspack 这类新一代构建工具它们确实是更快的方案但前期迁移成本和生态兼容成本都不低接入 Module Federation让多个应用共享运行时依赖从架构层面减少重复打包做 import 的 cost 分析团队里加一条构建检查规则超过指定体积的模块 import 给出 warning 甚至阻断把体积控制从“事后优化”变成“事前预防”。我个人在实际操作中的体会是构建优化更像是一次体系治理而不是某条配置的魔法。你改掉一个 loader存储缓存策略调整拆一个 chunk每个环节单独看效果都不算惊人但它们叠加起来就是几十秒到几秒、几 MB 到几百 KB 的差距。真正难的不是配置本身而是根据项目特性做出取舍以及每次改完都确保线上功能没有受到影响。工具一直在变但“先测量、再优化、后回归”这套方法论是永不过时的。最后分享一个小技巧在 package.json 的 build 脚本里加一条--json compile-stats.json输出每次构建完自动保存编译数据时间久了就是一份真实可信的优化成果记录。团队复盘、向领导汇报、新人接手排查性能问题这份数据比任何口头描述都管用。