Stylelint规则开发完全指南：从创建到优化的全流程

Stylelint规则开发完全指南：从创建到优化的全流程

stylelint A mighty CSS linter that helps you avoid errors and enforce conventions. 项目地址: https://gitcode.com/gh_mirrors/st/stylelint

前言

作为前端开发者，我们都深知CSS代码质量的重要性。Stylelint作为业界领先的CSS代码检查工具，其强大之处在于其灵活的规则系统。本文将深入讲解如何为Stylelint开发高质量的规则，帮助开发者理解规则的设计哲学和实现细节。

规则设计原则

在开始编写规则前，我们需要理解Stylelint规则的核心设计理念：

1. 单一职责原则：每个规则应该只检查一个特定的CSS模式或问题
2. 明确性原则：规则的完成状态应该是明确的，没有模糊地带
3. 通用性原则：规则应该适用于标准CSS语法，而不是特定模式

命名规范

规则名称采用两部分结构：

• 第一部分指定规则适用的CSS结构（如at-rule、selector等）
• 第二部分描述规则检查的内容（如disallowed-list、required-properties等）

例如：at-rule-disallowed-list表示检查不允许使用的@规则列表。

规则开发流程

1. 编写测试用例

良好的测试是规则开发的基础，应包含：

• 正向测试：应该报错的CSS模式
• 反向测试：不应该报错的CSS模式

测试编写建议：

• 使用真实的CSS代码片段
• 保持测试代码最小化
• 使用标准的选择器、属性和值
• 测试不同位置（行/列）的警告

常见边界情况

特别注意处理以下边界情况：

• CSS变量（var(--custom-property)）
• CSS全局关键字（initial、inherit等）
• 字符串内容（content: "任意内容"）
• 注释（/* 任意内容 */）
• 空函数（var()）
• URL函数（包括data URI）
• 厂商前缀（-webkit-等）
• 大小写敏感性
• 伪类和伪元素组合（如a:hover::before）
• 嵌套规则（如& a {}）
• 空格和标点差异（如rgb(0,0,0) vs rgb(0, 0, 0)）

2. 实现规则逻辑

PostCSS API使用

Stylelint基于PostCSS AST进行操作，推荐使用walk系列方法遍历节点：

root.walkDecls(decl => {
  // 处理每个声明节点
});

节点处理时，应先检查节点类型：

nodes.find(({ type, prop }) => type === "decl" && prop === "color")

专用解析器

根据规则类型选择合适的解析器：

• 值解析：postcss-value-parser
• 选择器解析：postcss-selector-parser
• 媒体查询解析：@csstools/media-query-list-parser

这些解析器比正则表达式更可靠，能正确处理复杂CSS语法。

工具函数

Stylelint提供了丰富的工具函数：

• validateOptions()：验证选项有效性
• isStandardSyntax*()：检查是否标准语法
• report()：报告问题

问题定位

使用report()时，有四种定位方式：

1. 整个节点：最简单但不精确
2. 关键词：查找节点中的特定词
3. 偏移量：通过index/endIndex指定范围
4. 位置对象：通过start/end位置指定

推荐使用偏移量或位置对象，它们更精确且性能更好。

3. 规则选项设计

主要选项

每个规则必须有一个主要选项，例如：

• "font-weight-notation": "numeric"
• "selector-max-type": 2

次要选项

用于处理特殊情况，通常包括：

• ignore：忽略特定模式
• except：对特定模式反转主要选项
• ignore*：用户自定义忽略列表

选项设计原则：

• 默认严格，通过选项放宽限制
• 只添加确实需要的选项
• 避免包含预处理语法相关逻辑

4. 错误信息

错误信息应清晰明确，格式为：

• "Expected [something] [in some context]"
• "Unexpected [something] [in some context]"

可自动修复的规则使用：

• 'Expected "[unfixed]" to be "[fixed]"'（短字符串）
• 'Expected "[primary]" ... notation'（长字符串）

5. 自动修复

实现自动修复需要：

1. 设置meta.fixable = true
2. 在report()中提供fix回调函数

const fix = () => {
  // 使用PostCSS API修改AST
};

report({
  // ...其他参数
  fix
});

6. 文档编写

规则文档应包含：

1. 规则名称
2. 单行描述
3. 原型代码示例
4. 详细说明（如有必要）
5. 选项说明
6. 错误示例（每种选项）
7. 正确示例（每种选项）
8. 可选选项（如适用）

文档编写技巧：

• 从测试用例中选取示例
• 只使用标准CSS语法
• 使用<!-- prettier-ignore -->保持代码格式
• 对齐箭头和文本

高级主题

性能优化

使用内置基准测试工具评估规则性能：

npm run benchmark-rule -- ruleName ruleOptions [config]

优化建议：

• 避免在循环中进行复杂计算
• 尽早返回以减少不必要处理
• 使用高效的节点遍历方法

规则维护

添加选项

1. 添加测试用例
2. 修改选项验证
3. 实现新逻辑
4. 更新文档
5. 更新类型定义

修复Bug

1. 编写重现Bug的测试
2. 修改规则直到测试通过

废弃规则

1. 设置meta.deprecated = true
2. 设置stylelintType: 'deprecation'
3. 提供替代方案参考链接

总结

开发高质量的Stylelint规则需要：

• 深入理解CSS语法和PostCSS AST
• 严谨的测试覆盖
• 清晰的选项设计
• 良好的性能意识
• 完整的文档

遵循这些原则，你就能为Stylelint生态系统贡献出专业级的规则，帮助开发者编写更高质量的CSS代码。

stylelint A mighty CSS linter that helps you avoid errors and enforce conventions. 项目地址: https://gitcode.com/gh_mirrors/st/stylelint