webpack-plugin-authoring

dot-skills Webpack 5 插件最佳实践

编写正确、高性能 webpack 5 插件的全面指南。包含 8 个类别中的 44 条规则（8 条 hook + 7 条 asset + 5 条 cache + 5 条 life + 4 条 schema + 5 条 diag + 5 条 perf + 5 条 compat = 44），按编写生命周期排序：hook 选择是基础，然后是 asset 操作、缓存和监视模式正确性、生命周期规范，接着是面向用户的问题（schema 验证、错误报告），最后是性能和打包。

这些模式源自 webpack/webpack、webpack-contrib 插件套件（mini-css-extract、terser、compression、copy、css-minimizer），以及 vercel/next.js 中 Next.js 的 webpack 集成。

适用场景

在以下情况下，参考这些规则：

• 编写新插件（定义 apply(compiler)、选择要 tap 的 hook）
• 检查现有插件代码的正确性或性能
• 调试“为什么我的插件没有输出”——通常是 hook/stage 不匹配
• 添加 asset 操作逻辑（processAssets、emitAsset、updateAsset）
• 修复监视模式下的数据过时问题或持久缓存污染
• 将插件从 webpack 4 迁移到 webpack 5（或同时支持两者）
• 将插件发布到 npm（导出形式、peerDependencies、schema）

按优先级划分的规则类别

优先级	类别	影响	前缀
1	Hook 选择与 Tap 模式	CRITICAL	hook-
2	Asset 管线	CRITICAL	asset-
3	缓存与监视模式	HIGH	cache-
4	插件生命周期与状态	HIGH	life-
5	Schema 与选项验证	MEDIUM-HIGH	schema-
6	错误、警告与日志记录	MEDIUM-HIGH	diag-
7	性能与并行处理	MEDIUM	perf-
8	兼容性与打包	LOW-MEDIUM	compat-

快速参考

1. Hook 选择与 Tap 模式（CRITICAL）

• hook-tap-method-matches-hook-type — 根据 hook 的 Sync/Async 类型匹配 tap/tapAsync/tapPromise
• hook-thiscompilation-vs-compilation — 使用 thisCompilation 跳过子编译
• hook-process-assets-stage — 根据你的修改选择合适的 PROCESS_ASSETS_STAGE_*
• hook-prefer-process-assets-over-emit — 在 processAssets 中修改，而不是在 emit 中修改
• hook-bail-hook-return-semantics — 除非有意停止，否则从 bail hooks 返回 undefined
• hook-tap-once-not-per-compilation — 在 apply 中注册 compiler hooks 一次，而不是在 compilation hooks 中注册
• hook-name-matches-class-name — 使用与类名一致的稳定 tap 名称
• hook-normal-module-factory-stages — 在正确的解析阶段（beforeResolve、resolve 或 afterResolve）tap normalModuleFactory

2. 资源管线（关键）

• asset-emit-asset-not-direct-assignment — 使用 emitAsset/updateAsset，绝不要执行 compilation.assets[name] = ...
• asset-source-from-compiler-webpack — 从 compiler.webpack.sources 导入 source 类
• asset-preserve-source-maps — 使用 SourceMapSource/ReplaceSource 保留映射
• asset-set-info-metadata — 发出资源时设置 info.immutable、info.contenthash、info.related
• asset-content-hash-via-output-options — 通过 compilation.outputOptions.hashFunction 计算哈希，而不是硬编码 md5
• asset-delete-then-emit-loses-info — 使用 renameAsset 移动资源；deleteAsset+emitAsset 会断开分块引用
• asset-buffer-not-source-for-binary — 二进制资源使用 buffer()，而不是 source()

3. 缓存与监视模式（高）

• cache-add-file-dependencies — 将读取的文件添加到 compilation.fileDependencies
• cache-context-dependencies-for-directories — 扫描目录时使用 contextDependencies
• cache-missing-dependencies-for-optional-files — 将已探测但不存在的路径添加到 missingDependencies
• cache-build-dependencies-for-persistent-cache — 声明 buildDependencies，以便持久化缓存失效
• cache-use-input-file-system — 通过 compiler.inputFileSystem 读取，而不是使用 Node fs

4. 插件生命周期与状态（高）

• life-constructor-stores-options-only — 构造函数只负责验证和存储；副作用应放在 apply() 中
• life-no-mutable-state-across-builds — 使用局部 const 或 WeakMap，将可变状态限定在每次编译中
• life-multi-compiler-isolation — 每个编译器使用一个插件实例；或使用 WeakMap<Compiler, T>
• life-cleanup-in-shutdown-hook — 在 compiler.hooks.shutdown 中清理工作线程、监视器和文件描述符
• life-defensively-copy-user-options — 绝不要修改用户的 options 对象

5. Schema 与选项验证（中高）

• schema-validate-with-schema-utils — 使用 schema-utils.validate() 和 JSON Schema 进行验证
• schema-name-and-base-data-path — 设置 name 和 baseDataPath，以便错误消息可导航
• schema-additional-properties-false — 对每个对象设置 additionalProperties: false，以发现拼写错误
• schema-tap-into-validate-hook — 将跨字段验证延后到 compiler.hooks.validate（5.106+）

6. 错误、警告与日志记录（中高）

• diag-push-webpack-error-not-throw — 将 WebpackError 推送到 compilation.errors，不要抛出
• diag-use-compilation-get-logger — 通过 compilation.getLogger('Plugin') 记录日志，而不是使用 console
• diag-attach-loc-to-errors — 为错误附加 loc 和 module，以支持 IDE 点击跳转
• diag-warnings-vs-errors-exit-codes — 错误会导致构建失败；警告不会——请谨慎选择
• diag-progress-reporting — 通过 context.reportProgress 报告进度（使用 context: true 启用）

7. 性能与并行处理（中）

• perf-jest-worker-for-cpu-bound-work — 将 CPU 密集型工作交给 jest-worker 线程池处理
• perf-cache-results-with-compilation-cache — 通过 compilation.getCache(name).providePromise 缓存开销较大的工作
• perf-traverse-chunks-not-modules — 尽可能遍历 compilation.chunks，而不是 compilation.modules
• perf-avoid-source-toString-in-hot-paths — 对只需检查的资源，避免调用 source().toString()
• perf-respect-experimental-options — 遵循 experiments.cacheUnaffected / incremental 设置

8. 兼容性与打包（低至中）

• compat-webpack-as-peer-dependency — 将 webpack 声明为 peerDependencies，而不是 dependencies
• compat-use-compiler-webpack-namespace — 使用 compiler.webpack.*，而不是 require('webpack')
• compat-custom-hooks-via-weakmap — 通过静态的 getCompilationHooks + WeakMap 暴露自定义钩子
• compat-feature-detection-not-version-check — 直接检测 API；不要解析 webpack/package.json 版本
• compat-export-shape-and-cjs-esm — 将插件类作为默认导出；提供 CJS/ESM 互操作

使用方法

编写或审查插件代码时，请查阅 AGENTS.md 中的相关类别，然后阅读对应的规则文件，了解完整模式及其依据。

• 从 references/_sections.md 开始，了解类别定义和影响级别
• 如果想扩展此技能，请参阅 assets/templates/_template.md 中的规则模板
• 阅读 AGENTS.md，查看精简的导航索引

参考文件

文件	描述
references/_sections.md	类别定义、影响级别、说明
assets/templates/_template.md	编写新规则的模板
metadata.json	版本、领域、来源参考