企业官网建设流程全解析

Stylelint 规则custom-property-empty-line-before：自定义属性空行规范配置全解

【免费下载链接】stylelintA mighty CSS linter that helps you avoid errors and enforce conventions.项目地址: https://gitcode.com/gh_mirrors/st/stylelint

导读

custom-property-empty-line-before是 Stylelint 内置规则之一，用于要求或禁止自定义属性（CSS 变量声明，如--foo: pink）之前存在空行，从而在样式表中统一自定义属性的排版节奏。它在设计系统变量分组、主题变量声明等场景中尤其有用。读完本文，你将掌握该规则的全部主/次选项含义、except与ignore的细微差异、共享行注释（shared-line comment）的特殊处理，以及其--fix自动修复能力与底层实现原理，可直接在真实项目中落地配置。

规则概览：它检查什么

该规则只作用于自定义属性声明，即属性名以--开头的声明（isCustomProperty.mjs 中实现为property.startsWith('--')），并通过 isStandardSyntaxDeclaration.mjs 过滤掉 SCSS 变量、非标准语法等节点。

规则要求自定义属性前面（decl.raws.before中）要么必须存在空行（"always"），要么必须不存在空行（"never"）。其核心判定逻辑位于 index.mjs：先由主选项得出期望值，再被except反向，最后与hasEmptyLine(decl.raws.before)的实际值比对，不一致即上报。

a { top: 10px; /* ← */ --foo: pink; /* ↑ */ } /* ↑ */ /** ↑ * This line */

上图中箭头指向的正是规则关注的“声明之前的空行”。

该规则是可自动修复（fixable）的：文档中声明meta.fixable = true（index.mjs），配合fix选项 可自动为所有该规则报告的问题插入或删除空行。同时，该规则没有消息参数（message arguments），与configure.md#message中的自定义消息机制不产生交互。

主选项（Primary Options）

主选项二选一，分别对应两种排版风格。

"always"：要求空行

{ "custom-property-empty-line-before": "always" }

以下写法视为问题（相邻的自定义属性之间没有空行）：

a { top: 10px; --foo: pink; --bar: red; }

以下写法不视为问题（每个自定义属性前都有空行）：

a { top: 10px; --foo: pink; --bar: red; }

"never"：禁止空行

{ "custom-property-empty-line-before": "never" }

以下写法视为问题（存在多余空行，包括块内第一个声明前有空行）：

a { top: 10px; --foo: pink; --bar: red; }

a { --foo: pink; --bar: red; }

以下写法不视为问题：

a { top: 10px; --foo: pink; --bar: red; }

a { --foo: pink; --bar: red; }

注意："never"模式下，块内首个声明前有换行导致的空行同样会被报告（见上方第二个“视为问题”示例），这与规则基于decl.raws.before判定的实现一致。

次级选项except：反向主选项

except用于对特定上下文反转主选项的期望值。可取值共 4 个：after-block、after-comment、after-custom-property、first-nested。底层通过 optionsMatches 匹配配置，匹配时执行expectEmptyLineBefore = !expectEmptyLineBefore（index.mjs）。

{ "except": ["array", "of", "options"] }

"after-block"：块之后的属性

反转“紧跟在规则块或 at-rule 块之后的属性”的空行期望。

{ "custom-property-empty-line-before": ["never", { "except": ["after-block"] }] }

以下写法不视为问题（never本应禁止空行，但after-block反转后允许）：

a { a {} --foo: red; }

a { @media all {} --foo: red; }

底层判定：前一个节点是rule或at-rule即视为“在块之后”（isAfterBlock.mjs）。

"after-comment"：注释之后的属性

反转“紧跟在注释之后的属性”的空行期望。共享行注释（shared-line comment）不触发本选项。

{ "custom-property-empty-line-before": [ "always", { "except": ["after-comment"] } ] }

以下写法视为问题（--bar前有空行，但它在独立注释行之后，期望被反转为“无空行”）：

a { --foo: pink; /* comment */ --bar: red; }

a { --foo: pink; /* comment */ --bar: red; }

以下写法不视为问题：

a { --foo: pink; /* comment */ --bar: red; }

a { --foo: pink; /* comment */ --bar: red; }

注意：上例中--foo: pink; /* comment */属于共享行注释场景，--bar并不被视为“跟在注释之后”，因此其空行仍按always要求处理。实现上，isAfterComment.mjs 只有在“前一节点是注释且该注释不是共享行注释”时才返回true。

"after-custom-property"：另一自定义属性之后

反转“紧跟在另一自定义属性之后的属性”的空行期望。共享行注释不影响本选项。

{ "custom-property-empty-line-before": [ "always", { "except": ["after-custom-property"] } ] }

以下写法视为问题（--bar前有空行，但它是自定义属性之后，期望被反转为“无空行”）：

a { --foo: pink; --bar: red; }

a { --foo: pink; /* comment */ --bar: red; }

以下写法不视为问题：

a { --foo: pink; --bar: red; }

a { --foo: pink; /* comment */ --bar: red; }

底层判定见 isAfterCustomProperty：通过 getPreviousNonSharedLineCommentNode.mjs 跳过共享行注释后，若前一节点是声明且属性以--开头则命中。

"first-nested"：父节点首个嵌套子节点

反转“作为其父节点第一个子节点（且位于嵌套环境中）的自定义属性”的空行期望。

{ "custom-property-empty-line-before": [ "always", { "except": ["first-nested"] } ] }

以下写法视为问题（--foo是a块内第一个嵌套子节点，本不应有空行，却存在空行）：

a { --foo: pink; --bar: red; }

以下写法不视为问题：

a { --foo: pink; --bar: red; }

底层判定见 isFirstNested.mjs：除“节点即parentNode.first”外，还考虑与开括号同行注释的情况——若父节点首个节点是同行注释，则其后第一个非该注释的节点仍被视为“首个嵌套子节点”。

次级选项ignore：跳过检查

ignore与except不同：命中后规则直接跳过该声明、不再检查，而非反转期望值。可取值共 4 个：after-comment、after-custom-property、first-nested、inside-single-line-block。

{ "ignore": ["array", "of", "options"] }

"after-comment"：忽略注释之后的属性

{ "custom-property-empty-line-before": [ "always", { "ignore": ["after-comment"] } ] }

以下写法不视为问题（--foo在注释之后，被直接忽略）：

a { /* comment */ --foo: pink; }

"after-custom-property"：忽略自定义属性之后的属性

{ "custom-property-empty-line-before": [ "always", { "ignore": ["after-custom-property"] } ] }

以下写法不视为问题（--bar跟在--foo之后，被忽略；而--foo前仍有空行满足always）：

a { --foo: pink; --bar: red; }

"first-nested"：忽略父节点首个嵌套子节点

{ "custom-property-empty-line-before": [ "always", { "ignore": ["first-nested"] } ] }

以下写法不视为问题（--foo是首个嵌套子节点，被忽略；--bar仍需遵守always）：

a { --foo: pink; --bar: red; }

"inside-single-line-block"：忽略单行块内的属性

{ "custom-property-empty-line-before": [ "always", { "ignore": ["inside-single-line-block"] } ] }

以下写法不视为问题（单行块内无从插空行，整体忽略）：

a { --foo: pink; --bar: red; }

底层判定：父节点为rule或at-rule且其整个块字符串是单行（isSingleLineString 判断 blockString 结果）时直接return（index.mjs）。

各选项组合使用示例

except与ignore均可多值组合，且可同时使用。以下为测试中验证过的典型组合：

{ "custom-property-empty-line-before": [ "always", { "except": ["first-nested", "after-comment", "after-custom-property"] } ] }

{ "custom-property-empty-line-before": [ "never", { "except": ["first-nested", "after-comment", "after-custom-property"] } ] }

组合逻辑在源码中是顺序执行的：先依次检查 4 个ignore（任一命中即跳过），再计算期望值并应用 4 个except反转（index.mjs）。从测试可见，except: ['first-nested', 'after-comment', 'after-custom-property']与always/never组合的复杂嵌套样式均可被正确接受（见tests/index.mjs）。

自动修复（--fix）行为详解

规则声明fixable: true，--fix模式下会报告自动修复问题。修复由 fixEmptyLinesBefore.mjs 完成：

• 期望空行而缺失时（action: 'add'）→ 调用 addEmptyLineBefore.mjs 在节点前插入一个空行；
• 期望无空行而存在时（action: 'remove'）→ 调用 removeEmptyLinesBefore.mjs 删除空行；
• 修复使用context.newline作为换行符，因此能保留原有的 LF / CRLF 风格。

测试用例（tests/index.mjs）对fix与computeEditInfo均有断言，例如：

• always下a {\n--custom-prop: value;\n}被修复为a {\n\n--custom-prop: value;\n}，且给出精确的编辑区间{ range: [3, 4], text: '\n\n' }；
• never下a {\n\n --custom-prop: value;\n}被修复为a {\n --custom-prop: value;\n}；
• CRLF（\r\n）场景同样有对应的 fixed 输出与编辑区间断言，证明该规则在不同换行符环境下均可安全修复。

若你不希望自动改动文件，也可仅依赖报告结果手动调整，或在 CLI 中不加--fix运行。

源码实现要点

该规则的完整实现位于 index.mjs，关键流程如下：

1. 选项校验：通过 validateOptions 校验主选项仅可为'always' | 'never'，次选项键为except/ignore，并限定各自允许值（index.mjs）；校验失败直接返回，不产生报告。
2. 遍历声明：root.walkDecls遍历所有声明，先过滤非标准语法与非自定义属性节点（index.mjs）。
3. 忽略判定：依次检查ignore的 4 种情况。
4. 期望计算与报告：计算期望值 → 比对hasEmptyLine→ 不匹配时通过 report 上报，消息为'Expected empty line before custom property'或'Expected no empty line before custom property'（index.mjs），并附带fix.apply回调供--fix使用。
5. 消息参数：messageArgs: []为空数组，印证文档所述“没有消息参数”。

其中“空行”的判定来自 hasEmptyLine.mjs：用正则/\n[\r\t ]*\n/检测节点raws.before中是否存在“两个换行之间只有空白”的片段，因此空行行内允许存在空格与制表符。

实际项目中的配置建议

在.stylelintrc或stylelint.config.mjs中按需启用：

{ "rules": { "custom-property-empty-line-before": ["always", { "except": ["first-nested"] }] } }

常见思路：

• 若你习惯将自定义属性集中在声明块顶部并分组，可用["always", { "except": ["first-nested"] }]：块内首个变量无需空行，其余自定义属性之间用空行分组；
• 若代码风格趋向紧凑，可用"never"并要求变量组与普通声明之间手动空行；
• 混合 SCSS/Less 项目无需担心，规则内部已通过isStandardSyntaxDeclaration过滤非标准声明，SCSS 变量（$var）不会触发该规则（测试中$var: value场景均在always下接受/正常修复）。

关于该规则与 Stylelint 其他*-empty-line-before系列规则（如at-rule-empty-line-before、rule-empty-line-before、comment-empty-line-before）的搭配使用，可参考 rules 文档 了解完整规则清单。

结语

custom-property-empty-line-before通过“主选项定基调 +except反转 +ignore豁免”的三层设计，把“自定义属性前是否有空行”这一看似简单的排版问题做到了细粒度可控，且完全支持--fix自动修复，兼容 LF/CRLF。结合本文对源码与测试的分析，你现在可以针对自己的设计系统与变量组织风格，精确配置这一规则并纳入 CI 校验。

【免费下载链接】stylelintA mighty CSS linter that helps you avoid errors and enforce conventions.项目地址: https://gitcode.com/gh_mirrors/st/stylelint