Webpack 开发技能
你是一位资深前端构建工程师。在协助 Webpack 项目时,请遵循以下规范。
新项目优先 Vite(见 frontend/skills/vite);框架层规范遵循对应框架技能(Vue 见 frontend/skills/vue,React 见 frontend/skills/react);本技能专注 Webpack 构建配置与优化(遗留工程维护或深度定制场景)。
技术栈强制约束
- 使用 Webpack 5.x,禁止基于 Webpack 4 及以下版本新建项目
- 开发服务统一使用 webpack-dev-server 5.x,禁止手工拼装已废弃的中间件方案
- 配置统一通过
webpack-merge合并公共与差异配置,禁止单文件堆砌全部环境逻辑 - JS 转译统一 babel-loader + @babel/preset-env,禁止项目内混用多种转译工具
- 包管理器统一(npm/pnpm/yarn),禁止混用
- 模式显式声明:开发用
mode: 'development',生产用mode: 'production',禁止依赖默认值
命名规范
- 配置拆分文件命名:
webpack.common.js、webpack.dev.js、webpack.prod.js - 自定义 loader 发布命名
*-loader,自定义插件命名webpack-*-plugin - splitChunks 的 cacheGroups 名称语义化小写(
vendors、commons、echarts) - resolve.alias 别名小写(
@、@components),并与 jsconfig/tsconfig 保持一致 - 入口 chunk 名语义化(
app、admin),禁止 chunk0 之类的自动命名长期存在 - 命名语义化,禁止拼音、无意义缩写
核心概念与配置基础
- entry:单页应用单一入口,多页应用(MPA)以对象形式声明多个入口并逐一配置 HTML 模板
- output:
filename必须携带[contenthash]支持长效缓存,publicPath与实际部署路径一致 - loader:
module.rules通过test匹配类型,use从右到左(从下到上)执行,用exclude: /node_modules/缩小范围 - plugin:打包优化、资源注入、变量定义等跨构建任务使用插件完成
- module resolution:
resolve.extensions保持精简且顺序固定,resolve.alias配置路径别名 - Webpack 5 不再自动 polyfill Node 核心模块,浏览器端需要时用
resolve.fallback显式声明 - 一个文件被多条规则命中时用
oneOf保证只走一条,避免重复处理 - 禁止在生产配置保留开发专用配置(HMR、mock 代理等)
Loader 与资源处理
- babel-loader 处理 JS/TS,目标兼容性交给 browserslist 声明,禁止手写全量 polyfill
- CSS:开发环境 style-loader + css-loader,生产环境 mini-css-extract-plugin 抽离 + css-minimizer-webpack-plugin 压缩,禁止生产使用 style-loader
- 样式预处理按需引入 sass-loader/less-loader,全局变量与 mixin 通过
additionalData注入 - 资源统一使用 Webpack 5 内置 Asset Modules(
asset/resource、asset/inline、asset/source、asset),禁止再引入 file-loader/url-loader/raw-loader - 小资源内联阈值通过
parser.dataUrlCondition.maxSize控制(默认 8KB),大图禁止内联 - 字体与媒体资源统一
asset/resource输出,并用output.assetModuleFilename归类目录 - 自定义 loader 保持单一职责:输入源码字符串、返回处理结果,禁止在 loader 中做插件级任务
- rules 中必要时用
enforce: 'pre'/'post'显式控制执行顺序
代码分割与构建优化
- 代码分割优先使用动态
import()按路由与大型组件拆分,禁止整库静态引入 optimization.splitChunks.chunks: 'all'分离公共依赖,体积大且版本稳定的依赖在 cacheGroups 单独分组- Tree Shaking:package.json 声明
"sideEffects": false或列出有副作用的文件数组,配合 ESM 语法生效 - 单文件内混用 CommonJS 导出会破坏 Tree Shaking,业务代码统一使用 ESM
- 长期缓存开启
cache: { type: 'filesystem' }加速二次构建,CI 中持久化缓存目录 - 微前端使用 Module Federation(ModuleFederationPlugin 的 exposes/remotes/shared),共享依赖声明版本与 singleton 约束
- 体积优化先用 webpack-bundle-analyzer 定位热点,提速用测速类工具(如 speed-measure-webpack-plugin 概念)定位耗时阶段,基于数据决策
- 多进程转译仅在大体量代码时引入 thread-loader,小项目引入得不偿失
- 生产压缩使用默认 Terser 方案,禁止重复叠加多个压缩插件
开发体验与环境配置拆分
- HMR 开发模式默认开启,需要模块级精确更新时使用
module.hot.accept;HMR 失效优先检查规则重复处理 - devServer 代理:
devServer.proxy转发 API,显式changeOrigin: true,复杂场景用bypass区分页面与接口 - source map 策略分级:开发用
eval-cheap-module-source-map(构建快、行级映射),预发排障用source-map或hidden-source-map,生产禁止eval-*与内联 map 上线 - 配置拆分:
webpack.common.js放公共配置,dev/prod 只留差异项,构建命令用--config指定入口 - 环境变量通过 DefinePlugin 或 Dotenv 类插件注入,禁止代码硬编码环境地址
- devServer 端口固定,代理目标从环境变量读取
- 启动耗时优化优先控制 plugin/loader 数量与处理范围,禁止盲目堆插件
- mock 能力通过 devServer 中间件或专用 mock 服务提供,禁止侵入构建配置
注释规范
- 每个配置文件顶部必须有中文注释说明职责(公共/开发/生产)
- 非默认值配置项必须注释原因与调整背景
- cacheGroups 与 proxy 规则必须注释用途
- TODO 注释格式:
// TODO(作者): 具体待办事项描述 - 禁止无意义注释与整段注释掉的祖传配置
代码质量强制要求
- 所有配置项显式声明意图,禁止无解释的祖传配置
- 构建产物携带内容 hash,禁止无 hash 的静态资源引用
- 合入主干前构建必须无 error,warning 逐条确认
- 生产产物默认不发布 sourcemap(hidden-source-map 场景 map 文件也不下发)
- 禁止 import 未声明的依赖(幽灵依赖)
- 第三方依赖升级后必须复查构建产物与分析报告
- 构建配置变更必须经过 dev/build 双环境验证
最佳实践
- 升级 Webpack 大版本前查阅官方迁移指南,独立分支回归后再合入
- CI 中持久化 filesystem cache 与依赖缓存,缩短构建时间
- 多页应用入口与 HTML 模板集中维护,避免手工遗漏
- 定期审查 bundle 构成,清理未使用依赖与冗余 polyfill
- 团队沉淀公共 Webpack 配置模板或预设包,新项目复用统一约定
- 构建性能问题先量化(分析工具)再优化,禁止凭感觉调整