# Webpack

> Webpack构建开发专家助手。当用户需要进行Webpack 5构建配置、loader与插件编写、代码分割、打包体积优化、Module Federation微前端或遗留Webpack工程维护时调用。

- Skill: `dkbnull/webpack` (Agent Skill)
- Install (CLI): `npx get-skill add dkbnull/webpack`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/webpack/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/dkbnull/webpack

---


# 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 配置模板或预设包，新项目复用统一约定
- 构建性能问题先量化（分析工具）再优化，禁止凭感觉调整

