webpack-plugin-recipes

dot-skills Webpack 5 插件最佳实践

包含 26 个贴近生产场景的 webpack 5 插件的实用指南，按它们解决的问题分类。每个示例都从清晰定义的问题陈述开始（“不使用这个插件，哪些地方会很麻烦”），展示朴素的非插件实现方式，然后提供一个完整可运行的插件（60–150 行），并附上说明、变体以及“何时不应使用”的指导。

本指南是 webpack-plugin-authoring 的配套内容：authoring 讲解如何正确编写任意插件；本指南则讲解针对具体痛点应该编写哪种插件。各示例还会交叉引用所应用的 authoring 规则。

何时使用

遇到以下情况时，请参考这些示例：

• 团队反复遇到一个“感觉应该用插件解决”的构建时问题（架构规则、预防密钥泄漏、资源整理）
• 需要将 webpack 输出集成到下游系统（SSR 服务、CDN、监控）
• 正在考虑编写自己的插件还是采用现有插件——这些示例会展示底层模式，帮助你判断是否合适
• 从其他打包工具迁移，需要重现框架风格的功能（文件系统路由、虚拟模块）
• 为新工程师提供 webpack 插件编写入门指导——这些示例提供了真实、端到端的示例

按优先级划分的示例类别

优先级	类别	影响	前缀
1	构建时防护措施	CRITICAL	guard-
2	构建元数据与清单	HIGH	meta-
3	虚拟模块与代码生成	HIGH	virtual-
4	代码转换	MEDIUM-HIGH	transform-
5	开发者体验	MEDIUM	dx-
6	资源管线	MEDIUM	assets-

快速参考

1. 构建时防护措施（CRITICAL）

• guard-bundle-budget — 初始 JS 超出每个入口的 gzip 预算时，让构建失败
• guard-forbidden-imports — 禁止的导入跨越架构边界时，让构建失败
• guard-required-env-vars — 缺少必需环境变量时，让构建失败
• guard-no-secrets-bundled — 密钥特征字符串泄漏到客户端 bundle 时，让构建失败

2. 构建元数据与清单（HIGH）

• meta-inject-build-info — 通过 DefinePlugin 将 __COMMIT__/__BUILD_TIME__ 注入源码，并生成 build-info.json
• meta-asset-manifest — 生成按 chunk 分组、将逻辑名称映射到哈希文件名的清单
• meta-license-notice — 遍历模块图（而不是 node_modules/）生成 LICENSES.txt
• meta-sri-manifest — 为每个资源计算 SHA-384 SRI 哈希，以符合 CSP 要求

3. 虚拟模块与代码生成（HIGH）

• virtual-module-from-memory — 将 virtual:X 导入解析为内存中的字符串（Vite 风格）
• virtual-routes-from-filesystem — 从 pages/ 目录生成路由映射（Next.js 风格）
• virtual-barrel-from-directory — 自动生成目录的 barrel 再导出
• virtual-types-from-runtime — 根据运行时数据生成 .d.ts（配置文件、JSON schema）

4. 代码转换（中高）

• transform-replace-library — 在解析时将 react 替换为 preact/compat（支持子路径处理）
• transform-strip-debug-helpers — 从生产环境中移除 devAssert()/devLog() 调用和仅用于开发环境的导入
• transform-conditional-polyfill — 仅注入目标浏览器实际需要的 polyfill（browserslist + core-js-compat）
• transform-banner-with-dynamic-content — 为每个代码块添加包含当前年份、版本和 git 提交的信息横幅
• transform-define-from-config — 根据 flags/staging.json 风格的文件驱动 DefinePlugin 替换

5. 开发者体验（中）

• dx-build-duration-report — 持久化构建耗时；当前构建比中位数慢 30% 以上时发出警告
• dx-notify-on-done — 构建完成时发送桌面通知（本地）和 Slack webhook（CI）
• dx-diff-changed-chunks — 仅打印重新构建之间实际发生变化的代码块
• dx-open-browser-on-first-build — 首次成功构建后打开开发服务器 URL（而非之前）

6. 资源管线（中）

• assets-pre-compress-gzip-brotli — 为 CDN 服务的资源生成 .gz/.br 同级文件，用于预压缩
• assets-optimize-images — 使用 imagemin 优化 PNG/JPEG，并在重新构建时复用缓存
• assets-route-by-type — 将生成的资源整理到 js//css//img//fonts/ 子目录中
• assets-skip-empty-chunks — 删除 webpack/splitChunks/mini-css 不必要地生成的 0 字节代码块
• assets-add-cache-busting-query — 在固定文件名资源（manifest.json、sw.js）的引用后追加 ?v=<hash>

使用方法

当用户描述 webpack 问题（或请求编写插件）时：

1. 确定问题类别（防护措施？元数据？代码生成？转换？开发者体验？资源？）
2. 打开匹配的配方文件——先阅读 Problem 部分，确认它是否适用
3. 将 Plugin 部分作为可用的起点，并根据项目的具体情况调整
4. 阅读 How it works，了解每项设计选择背后的原因（其中会交叉引用编写规则）
5. 查看 Variations，了解常见调整；并查看 When NOT to use，确认是否适用

若要更全面地学习插件编写模式，可配合使用 webpack-plugin-authoring 技能——其中的 44 条规则讲解了此技能中每个配方所用的底层 API。

参考文件

文件	描述
references/_sections.md	类别定义和影响级别
assets/templates/_template.md	编写新配方的模板
metadata.json	版本和来源参考