Gutenberg 的 wordpress/dependency-group 规则解析依赖分组注释的强制与禁用的完整指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg这篇技术指南聚焦 Gutenberg 仓库中wordpress/eslint-plugin插件提供的dependency-group规则它负责对顶层包导入语句强制always或禁止never依赖分组注释块。文章将以官方规则文档为骨架结合 规则源码 与 测试用例 的逐行剖析帮助你在自己的 WordPress/Gutenberg 项目中理解该规则的三分类判定逻辑、容错匹配策略、自动修复行为以及如何在 flat config 中正确配置启用。一、规则是什么为顶层导入强制执行依赖分组注释dependency-group是 wordpress/eslint-plugin 提供的一个布局类meta.type为layout规则。它的职责是对顶层作用域中的包导入语句要求或禁止其前置一段依赖分组注释块用于标注导入的来源类别。该规则的完整定义位于 packages/eslint-plugin/rules/dependency-group.js并在 packages/eslint-plugin/index.js 中通过rules: require( ./rules )统一注册因此启用插件后即可通过规则名wordpress/dependency-group引用。原文档明确指出Gutenberg 自身的编码规范位于仓库 docs/contributors/code 目录采用一段连续的 import 块且不使用依赖分组注释。结合 CHANGELOG.md 中 6.0.0 与 24.0.0 两次变更记录该规则早已从custom与recommended预设中移除成为按需启用的 opt-in 特性——这正是本规则对项目配置是显式添加、而非默认生效的原因。二、核心机制导入来源的三种分类locality规则的底层逻辑建立在依赖属地locality分类之上。源码 getPackageLocality 依据导入源字符串的前缀做判定分类locality判定条件典型示例Internal内部依赖源字符串以.开头import edit from ./edit;WordPressWordPress 依赖源字符串以wordpress/开头import { Component } from wordpress/element;External外部依赖其余所有情况import { camelCase } from change-case;从源码结构可以推断WordPress是 Gutenberg 生态的专属分类用于区分wordpress/*包与普通的 npm 第三方包而以.开头的相对路径导入如./、../被归类为Internal。三种分类共同覆盖了 import 语句几乎全部来源形态。值得一提的是规则同时支持 ES Module 的import语句与 CommonJS 的require()调用。Program访问器会遍历顶层子节点对ImportDeclaration直接读取child.source.value对VariableDeclaration则检查其初始化表达式是否为require( ... )调用且参数为字符串字面量dependency-group.js#L239-L277。CHANGELOG 22.22.0 记录了一次针对require()识别的 Bug 修复正是这一能力演进的注脚。三、Optionsalways与never两种模式规则接受单个选项取自枚举[always, never]由 schema 约束不传时默认值为always见 dependency-group.js#L21always默认强制依赖分组注释必须存在never禁止依赖分组注释存在。原文档给出的经典 JSON 配置适用于 eslintrc 时代规则名需带插件前缀wordpress/{ rules: { wordpress/dependency-group: [ error, always ] } }若要禁止分组注释{ rules: { wordpress/dependency-group: [ error, never ] } }需要说明的是当前仓库已全面采用 ESLint v9/v10 的 flat config。由于该规则不在任何预设中若在eslint.config.mjs中使用需在规则覆盖中显式声明可参考 README.md 中 flat config 的用法import wordpress from wordpress/eslint-plugin; export default [ ...wordpress.configs.recommended, { rules: { wordpress/dependency-group: [ error, always ], }, }, ];四、always模式分组注释的强制与自动修复4.1 违规与合规示例不正确的代码缺少分组注释import { camelCase } from change-case; import { Component } from react; import edit from ./edit;正确的代码三种依赖各有注释块/* * External dependencies */ import { camelCase } from change-case; /* * WordPress dependencies */ import { Component } from react; /* * Internal dependencies */ import edit from ./edit;4.2 源码级判定逻辑在always模式下规则只针对顶层作用域的导入节点匹配Program节点并检查其body子节点而非直接匹配 import 节点见 dependency.js#L236-L238。每条导入按其 locality 分组每个分类只报告一次Program访问器通过verified集合去重dependency-group.js#L279-L287否则修复器会为每一条 import 各插入一个注释块产生大量冗余。判定函数 getDependencyBlockCorrection 会扫描导入节点之前的所有注释检查是否已存在满足该 locality 的注释块若存在但内容不精确则返回一个包含可复用注释节点与期望值的修正对象。4.3 容错匹配tolerances匹配并非逐字精确源码 isLocalityDependencyBlock 的正则允许以下容错注释风格归一化/** ... */与/* ... */均被接受大小写不敏感Dependencies与dependencies等价正则带i标志结尾句号可省略dependencies与dependencies.均匹配Node是External的别名Node dependencies被视为External dependencies。这些容错保证历史代码中各种手写变体的分组注释都能被正确识别而不是被误报后强制重写。4.4 自动修复fixer规则声明了fixable: code可被eslint --fix自动处理。当注释块缺失时修复器在导入节点前插入标准注释文本dependency-group.js#L311当注释块存在但内容需规范化时则用期望值替换原注释dependency-group.js#L304-L308。期望注释的文本由 getCommentValue 生成最终形态如/*\n * External dependencies\n */。五、never模式禁止分组注释并保留普通注释5.1 违规与合规示例不正确的代码出现依赖分组注释/* * External dependencies */ import { camelCase } from change-case; /* * Internal dependencies */ import edit from ./edit;正确的代码连续导入块无任何分组注释import { camelCase } from change-case; import { Component } from react; import edit from ./edit;5.2 源码级判定与修复never模式在Program访问器中遍历全部注释凡被 isDependencyBlock 判定为依赖分组块的即 External/WordPress/Internal 任一分类命中容错正则均以Unexpected dependency group comment block上报。修复器 dependency-group.js#L189-L210 的删除逻辑非常考究它会向前修剪连续的多余换行、向后吞掉尾部换行再移除整段注释区间从而不留下空行残骸。关键在于它只删除依赖分组注释——如 测试用例 所示形如/** Keep external dependencies up to date. */的普通说明性注释会被保留因为其内容不匹配分组正则该项增强记录于 CHANGELOG 的 25.8.0 之后版本never模式可识别大小写/句号变体同时保留其他注释。六、边界情况与never模式相关的判定变体综合 测试用例 的valid与invalid集合可整理出两个模式共同遵守的边界规则分组注释的大小写、结尾句号、Node别名在never模式下同样会被识别invalid用例覆盖了external Dependencies.、NODE DEPENDENCIES、wordpress dependencies.、internal Dependencies.等变体并逐一上报仅为说明用途、不含External/WordPress/Internal dependencies结构的注释不会触发never违规规则只关心顶层导入Program的直接子节点函数体内或条件块内的导入不在检查范围测试环境同时覆盖了import与require()两种语法形态dependency-group.js#L15-L51。七、规则在 Gutenberg 中的定位与版本演进从 CHANGELOG.md 可梳理出该规则的关键演进2.4.0随wordpress/dependency-group规则一同引入作为新规则发布6.0.0与wordpress/gutenberg-phase一同从custom与recommended配置中移除改为 opt-in 特性不再默认启用22.22.0修复 CommonJSrequire()导入的识别问题24.0.0再次强调该规则不再被推荐25.8.0新增never模式支持禁止分组注释25.9.0 前后never模式增强为对大小写、结尾句号均能识别并在此过程中保留非分组注释。上述演进与文档中的表述Gutenberg 编码规范使用一段不含分组注释的连续 import 块相互印证Gutenberg 自身选择了never风格而always模式主要服务于采用分组式导入约定的第三方项目。八、总结与配置建议dependency-group是一个轻量但精巧的布局类规则其价值在于将导入来源是否清晰可辨这一团队约定形式化并通过eslint --fix做到零手工维护。实践要点如下默认不启用规则需在 flat config 或 eslintrc 中显式配置always为默认选项选择模式即选择风格Gutenberg 自身走never连续 import 块沿用该风格的项目可直接照搬偏好三段式分组的项目选择always放心交给 fixer两种模式均支持自动修复且修复逻辑对换行、注释风格、非分组注释均做了容错处理双语法覆盖ES Moduleimport与 CommonJSrequire()均被识别适用于混合模块体系的老项目。如需深入源码细节可继续阅读 规则实现、完整测试套件 以及 规则官方文档。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
