webpack-plugin-authoring

用途：面向编写或评审 webpack 5 插件的开发者，提供一套按插件编写生命周期排序的规则集，帮助正确选择钩子、处理资源管线、保证缓存与监听模式正确性，并兼顾生命周期、用户可见行为、性能与打包。资料称共 44 条规则，分 8 个类别，优先级从高到低为：钩子选择与 tap 模式（hook-，关键）、资源管线（asset-，关键）、缓存与监听模式（cache-，高）、插件生命周期与状态（life-，高）、schema 与选项校验（schema-，中高）、错误警告与日志（diag-，中高）、性能与并行（perf-，中）、兼容性与打包（compat-，中低）。模式取自 webpack/webpack、webpack-contrib 插件套件（mini-css-extract、terser、compression、copy、css-minimizer）以及 vercel/next.js 的 webpack 集成。适用时机包括：编写新插件（定义 apply(compiler)、选择要 tap 的钩子）、评审现有代码、排查插件输出不出现（通常是钩子或阶段不匹配）、增加资源操作逻辑（processAssets、emitAsset、updateAsset）、修复监听模式陈旧或持久缓存污染、从 webpack 4 迁移或同时支持两者、发布插件到 npm（导出形状、peerDependencies、schema）。部分要点举例：tap/tapAsync/tapPromise 需匹配钩子同步或异步类型；用 thisCompilation 跳过子编译；按变更类型选择 PROCESS_ASSETS_STAGE_；在 processAssets 中变更而非 emit；bail 钩子除有意停止外应返回 undefined；编译器钩子在 apply 中只注册一次；用 emitAsset/updateAsset 而非直接赋值 compilation.assets；从 compiler.webpack.sources 导入 source 类；用 SourceMapSource/ReplaceSource 保留 source map；设置 info.immutable、contenthash、related；用 compilation.outputOptions.hashFunction 而非硬编码 md5；用 renameAsset 移动资源；二进制资源用 buffer() 而非 source()；将读取文件加入 fileDependencies、目录扫描用 contextDependencies、探测但不存在的路径加入 missingDependencies、持久缓存声明 buildDependencies；通过 compiler.inputFileSystem 读取；构造函数只校验与存选项，副作用放 apply()；避免跨构建可变状态，用每次编译局部 const 或 WeakMap；多编译器隔离；在 compiler.hooks.shutdown 清理；不修改用户选项对象；用 schema-utils.validate() 与 JSON Schema 校验，设置 name 与 baseDataPath，开启 additionalProperties: false，跨字段校验延迟到 compiler.hooks.validate（5.106+）；向 compilation.errors 推送 WebpackError 而非抛出；用 compilation.getLogger 而非 console；错误附带 loc 与 module；错误与警告影响退出码需有意选择；用 context.reportProgress 报告进度（需 context: true）；CPU 密集任务交给 jest-worker；用 compilation.getCache(name).providePromise 缓存结果；尽量遍历 compilation.chunks；热点路径避免 source().toString()；尊重 experiments.cacheUnaffected/incremental；webpack 声明为 peerDependencies；使用 compiler.webpack.；自定义钩子经静态 getCompilationHooks 与 WeakMap 暴露；用特性检测而非版本号判断；导出插件类为 default 并提供 CJS/ESM 互操作。使用方式：编写或评审时先在 AGENTS.md 查找相关类别，再读单条规则文件了解完整模式与理由；分类定义与影响等级见 references/_sections.md，规则模板见 assets/templates/_template.md，导航索引见 AGENTS.md，另附 metadata.json 记录版本、领域与来源。限制：资料未提供具体安装命令、代码示例全文、收费或价格信息，这些暂未提供。