Stylelint自定义规则配置教程

本篇文章主要是结合我之前面试的各种经历和实战开发中遇到的问题解决经验整理的，希望这篇《Stylelint自定义规则实战教程》对你有很大帮助！欢迎收藏，分享给更多的需要的朋友学习~

自定义Stylelint规则能将团队CSS规范自动化，核心步骤是创建插件模块、编写规则逻辑并集成到项目配置中，通过本地引用或发布为npm包实现复用，需结合测试、CI流程和团队协作进行长期维护。

CSS工具Stylelint的自定义规则，在我看来，它更像是一种“量体裁衣”的能力，让我们能够超越那些通用、标准化的CSS规范，真正把项目的独特风格和最佳实践固化下来。它不是简单地修修补补，而是深入到代码结构和语义层面，为团队的CSS代码质量保驾护航。

解决方案

要应用Stylelint的自定义规则，核心步骤是编写一个Stylelint插件，并在项目的.stylelintrc.js配置文件中引用它。

首先，你需要创建一个Node.js模块来承载你的自定义规则。这个模块通常包含一个主入口文件（比如index.js）和一个或多个规则文件（比如rules/my-custom-rule.js）。

在rules/my-custom-rule.js中，一个自定义规则的基本结构是这样的：

const stylelint = require('stylelint');
const selectorParser = require('postcss-selector-parser'); // 用于解析选择器

const ruleName = 'my-project/no-unprefixed-colors'; // 规则名称，推荐使用项目前缀
const messages = stylelint.utils.ruleMessages(ruleName, {
  expected: (value) => `颜色值 "${value}" 必须使用 CSS 变量`,
});

// 规则的核心逻辑
const rule = (primaryOption, secondaryOptions) => {
  return (root, result) => {
    const validOptions = stylelint.utils.validateOptions(result, ruleName, {
      actual: primaryOption,
      possible: [true], // 我们的规则只需要一个布尔值来开启
    });

    if (!validOptions) {
      return;
    }

    // 遍历所有的声明（declarations）
    root.walkDecls((decl) => {
      // 检查是否是颜色相关的属性，并且值不是CSS变量
      if (
        /color|background-color|border-color/.test(decl.prop) &&
        !decl.value.startsWith('var(--') &&
        // 排除透明色等特殊情况
        !['transparent', 'currentColor', 'inherit'].includes(decl.value.toLowerCase())
      ) {
        stylelint.utils.report({
          message: messages.expected(decl.value),
          node: decl,
          result,
          ruleName,
        });
      }
    });

    // 也可以遍历选择器、at-rules等，根据你的需求
    // root.walkRules((ruleNode) => {
    //   selectorParser((selectors) => {
    //     selectors.walkClasses((classNode) => {
    //       // 检查类名是否符合BEM规范等
    //     });
    //   }).processSync(ruleNode.selector);
    // });
  };
};

rule.ruleName = ruleName;
rule.messages = messages;
module.exports = stylelint.createPlugin(ruleName, rule);

然后在你的插件的index.js中导出它：

// index.js
const rules = {
  'no-unprefixed-colors': require('./rules/my-custom-rule'),
};

module.exports = {
  rules,
  ruleNames: Object.keys(rules).map((key) => `my-project/${key}`),
};

最后，在你的项目根目录下的.stylelintrc.js（或者.stylelintrc.json）中引用这个插件：

// .stylelintrc.js
module.exports = {
  plugins: [
    './path/to/your/stylelint-plugin/index.js', // 指向你的插件入口文件
  ],
  rules: {
    'my-project/no-unprefixed-colors': true, // 启用你的自定义规则
    // 其他Stylelint规则...
  },
};

这样，当你运行Stylelint时，它就会加载并执行你的自定义规则了。

为什么我们需要自定义Stylelint规则？标准规则不够用吗？

我个人觉得，标准Stylelint规则固然强大，覆盖了绝大多数通用的CSS最佳实践，比如避免空规则、属性顺序、单位校验等等。但“够用”这个词，其实挺主观的，也挺挑项目的。对于一些大型项目、有严格设计系统规范的团队，或者采用了某些特定CSS方法论（比如BEM、Utility-first CSS）的项目来说，标准规则往往显得“心有余而力不足”。

这就像一套通用尺码的衣服，虽然能穿，但总有些地方不合身。比如，我们项目可能规定所有颜色值必须使用CSS变量，除非是transparent或currentColor这种特殊关键字。标准Stylelint规则很难直接检查这种高度定制化的逻辑。又或者，我们对组件的类名有非常严格的BEM命名约定，或者禁止在非特定文件中使用!important。这些都是标准规则无法触及的“深水区”。

在我看来，自定义规则的价值，就在于它能把团队内部的“隐形规范”显性化、自动化。它将那些口头约定、Code Review时反复强调的细节，变成了一条条机器可执行的校验逻辑。这不仅能大大提高Code Review的效率，减少人为疏忽，还能确保整个团队的CSS代码风格高度一致，尤其在多人协作时，这种统一性带来的好处是巨大的。它让我们的代码质量管理，从“人治”走向了“法治”，并且是“项目专属法治”。

开发一个简单的Stylelint自定义规则有哪些关键步骤和注意事项？

开发一个Stylelint自定义规则，其实是个挺有意思的过程，它要求我们深入理解CSS的结构，以及Stylelint内部的工作机制。

关键步骤：

1. 明确需求与痛点： 这是第一步，也是最重要的一步。你到底想检查什么？为什么标准规则做不到？把规则的意图、要校验的CSS模式和期望的错误信息都想清楚。比如，我要禁止在非_utilities.scss文件中使用!important。
2. 环境搭建： 初始化一个Node.js项目，安装stylelint、postcss（Stylelint底层使用PostCSS解析CSS）、stylelint-plugin（这是Stylelint提供的一个工具函数，用于创建插件）。如果你需要解析选择器，还需要postcss-selector-parser。
3. 规则结构设计： 按照前面解决方案中提到的，创建index.js作为插件入口，以及rules/your-rule-name.js来承载具体的规则逻辑。定义好ruleName（带项目前缀是好习惯，避免冲突），messages（清晰的错误提示是用户的福音），以及meta（可选，但对于发布到npm的插件很有用）。
4. 核心逻辑编写（AST遍历）：
   • Stylelint的规则函数会接收root（PostCSS的AST根节点）和result对象。
   • 利用root对象提供的各种walk方法，比如root.walkDecls()（遍历所有声明）、root.walkRules()（遍历所有规则集，如.foo {}）、root.walkAtRules()（遍历所有@规则，如@media {}），来找到你感兴趣的CSS节点。
   • 当找到符合条件的节点时，使用stylelint.utils.report()来报告错误。这个函数需要message、node（哪个节点出错了）、result和ruleName。
5. 编写测试： 这是我极力推荐的一步，甚至可以先写测试。stylelint-test-rule-tester是个很棒的工具。它能让你轻松地定义“应该通过的CSS”和“应该报错的CSS”，确保你的规则逻辑正确无误，并且能覆盖各种边界情况。没有测试的自定义规则，就像没有安全带的汽车，迟早会出问题。

注意事项：

• PostCSS AST理解： 理解PostCSS的抽象语法树（AST）是关键。知道root、rule、decl、atRule等节点的结构和它们提供的属性（如prop、value、selector等）能让你事半功倍。
• 性能考量： 避免在遍历过程中执行过于复杂的同步操作，尤其是在大型CSS文件中。如果规则逻辑非常复杂，可以考虑优化遍历方式。
• 错误信息清晰化： 错误信息是给开发者看的，一定要简洁明了，指出问题所在，最好能提供修改建议。
• 可配置性： 如果你的规则可能在不同场景下有细微差别，考虑给它添加选项（primaryOption和secondaryOptions），增加灵活性。
• 边界情况处理： 考虑CSS的各种写法，比如注释、空行、不同预处理器（SCSS/Less）的语法差异（虽然Stylelint会处理大部分，但特定规则可能需要注意）。
• 避免过度设计： 先实现核心功能，再考虑扩展性。一个简单但有效的规则，胜过一个复杂但 Bug 缠身的规则。

如何将自定义规则集成到现有项目中并进行维护？

将自定义规则集成到现有项目中，并确保其长期健康运行，这不仅仅是技术活，更关乎团队协作和流程管理。

集成方式：

1. 本地引用（适用于小型项目或快速验证）：
   • 最直接的方式就是把你的自定义规则文件（或整个插件目录）放在项目内部，比如./stylelint-plugins/my-custom-rule/index.js。
   • 然后在.stylelintrc.js的plugins数组中直接引用这个本地路径：plugins: ['./stylelint-plugins/my-custom-rule/index.js']。
   • 这种方式简单，但如果多个项目需要复用，或者插件变得复杂，管理起来会比较麻烦。
2. 发布为npm包（推荐，适用于大型项目或多项目复用）：
   • 将你的自定义规则插件作为一个独立的npm包发布。
   • 在项目中通过npm install your-stylelint-plugin安装。
   • 然后在.stylelintrc.js中引用：plugins: ['your-stylelint-plugin']。Stylelint会自动查找node_modules中的插件。
   • 这种方式标准化，易于版本管理和跨项目复用，但需要额外的发布流程。

维护策略：

1. 版本控制与文档：
   • 无论本地引用还是npm包，都应该将其纳入版本控制。
   • 为你的自定义规则编写清晰的README文件，说明其作用、配置选项、示例以及可能存在的已知问题。这对于新加入的团队成员理解和使用规则至关重要。
2. 持续集成（CI）：
   • 将Stylelint检查集成到你的CI/CD流程中。每次代码提交或合并请求时，自动运行Stylelint。
   • 如果自定义规则检查失败，CI应该阻止代码合并，确保只有符合规范的代码才能进入主分支。这能有效地强制执行规则。
3. 团队沟通与培训：
   • 引入新的自定义规则时，务必与团队成员进行充分沟通，解释规则的目的、解决的问题以及如何遵守。
   • 可以通过内部文档、分享会等形式进行培训，确保大家理解规则的价值，而不是将其视为额外的负担。
4. 定期审查与迭代：
   • CSS规范和项目需求是会变化的。建议定期（比如每季度或每半年）审查现有的自定义规则，看它们是否仍然适用，是否有新的需求出现，或者某些规则是否已经过时。
   • 根据项目的发展和团队的反馈，对规则进行调整、优化或新增。
5. 错误处理与日志：
   • 确保你的规则在处理异常或不规范的CSS时，能给出友好的错误提示，而不是直接崩溃。
   • 在某些复杂场景下，你可能需要在规则内部添加一些日志输出，帮助调试。

自定义规则的维护，其实就是对团队CSS规范的持续投入。它不是一劳永逸的事情，而是需要像维护其他核心代码一样，保持关注和迭代。通过这些努力，自定义规则才能真正成为项目质量的“守门员”，而不是一个摆设。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。