StyleLint集成实战：统一团队CSS代码规范的高效方案

又踩坑了，StyleLint 集成搞崩了整个构建流程

上周重构一个老项目，想把 StyleLint 加进去统一 CSS 代码规范。结果一配完，CI 直接红了，本地开发也跑不起来。折腾了快一天，最后发现是配置顺序和解析器的问题——这里我踩了个大坑。

最开始我以为就是装个包、写个配置的事。npm install stylelint stylelint-config-standard --save-dev，然后建个 .stylelintrc.json，照着文档抄了个基础配置：

{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "at-rule-no-unknown": true,
    "declaration-block-trailing-semicolon": "always"
  }
}

然后在 package.json 里加个脚本："lint:css": "stylelint "src/**/*.{css,scss}""。跑一下，报了一堆错，比如 Unknown word (CssSyntaxError)。我一开始以为是 SCSS 语法不支持，赶紧装了 postcss-scss，改配置：

{
  "extends": ["stylelint-config-standard"],
  "customSyntax": "postcss-scss",
  "rules": {
    "at-rule-no-unknown": [true, { "ignoreAtRules": ["tailwind", "apply", "variants", "responsive", "screen"] }]
  }
}

但还是不行，错误变成了 Cannot find module 'postcss-scss'。我检查了 node_modules，明明装了啊！后来才意识到，StyleLint 15+ 版本之后，不再内置 PostCSS，必须显式指定 customSyntax 并且确保依赖正确安装。于是我重新装了一遍：

npm install postcss postcss-scss --save-dev

注意，这里必须同时装 postcss，因为 postcss-scss 是它的插件，没主程序跑不起来。这一步很多人漏掉，包括我。

核心代码就这几行，但顺序很重要

真正让我卡住的是，在 Vite 项目里集成 StyleLint 的时候，我试图用 vite-plugin-stylelint 插件自动在 dev 时检查。结果一启动就报错，说找不到 postcss 配置。我翻了插件源码，发现它内部会尝试读取项目的 PostCSS 配置，但我的项目根本没用 PostCSS（纯 SCSS + Vite 原生处理）。

折腾了半天发现，其实根本不需要额外插件。Vite 本身对 CSS 的处理已经足够，StyleLint 只是个静态检查工具，完全可以独立运行。于是我把 vite-plugin-stylelint 删了，改用更简单的方式：只在 pre-commit 和 CI 里跑 lint，开发时靠编辑器插件实时提示。

最终的 .stylelintrc.json 长这样：

{
  "extends": ["stylelint-config-standard-scss"],
  "customSyntax": "postcss-scss",
  "rules": {
    "at-rule-no-unknown": [true, {
      "ignoreAtRules": [
        "tailwind",
        "apply",
        "layer",
        "config",
        "screen",
        "each",
        "for",
        "if",
        "else"
      ]
    }],
    "function-no-unknown": [true, {
      "ignoreFunctions": ["theme"]
    }],
    "property-no-unknown": [true, {
      "ignoreProperties": ["/^--/"]
    }],
    "selector-class-pattern": "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
    "color-function-notation": "modern",
    "alpha-value-notation": "number"
  },
  "ignoreFiles": ["**/*.js", "**/*.ts", "**/*.vue", "**/node_modules/**", "**/dist/**"]
}

几个关键点：

• 直接用 stylelint-config-standard-scss，它已经内置了对 SCSS 的支持，比手动 extend standard 再加 customSyntax 更稳妥
• at-rule-no-unknown 必须忽略 Tailwind 和 SCSS 控制指令（如 @each, @if），否则满屏报错
• 自定义属性（--xxx）要通过 property-no-unknown 的正则忽略，不然会被当成无效属性
• 别忘了 ignoreFiles，避免扫描非样式文件

然后在 package.json 里加两个脚本：

{
  "scripts": {
    "lint:css": "stylelint "src/**/*.{css,scss,vue}"",
    "lint:css:fix": "stylelint "src/**/*.{css,scss,vue}" --fix"
  }
}

注意路径里加了 .vue，因为我们的单文件组件里有 <style> 标签。StyleLint 能自动识别并提取样式块，但前提是 customSyntax 要能处理嵌入的 SCSS。好在 postcss-scss 对 Vue 单文件组件的支持还不错，只要你的 <style lang="scss"> 写对了就行。

踩坑提醒：这三点一定注意

第一，别混用 stylelint 和 stylelint-scss 插件的旧版配置。早期很多人会单独装 stylelint-scss 然后手动加 rules，现在官方推荐直接用 stylelint-config-standard-scss，它已经整合了这些规则。我一开始混着用，导致某些规则冲突，比如 scss/at-rule-no-unknown 和 at-rule-no-unknown 同时生效，报错重复。

第二，VS Code 插件要配对。我装了官方 StyleLint 插件，但默认它不知道用 postcss-scss 解析。得在 VS Code 的 settings.json 里加一行：

{
  "stylelint.customSyntax": "postcss-scss"
}

不然编辑器里一片红，但命令行却正常，这种割裂感特别折磨人。

第三，–fix 不是万能的。它能自动修复缩进、分号、引号这类问题，但像命名规范（selector-class-pattern）或者禁用某属性，它不会改。所以别指望跑一次 fix 就万事大吉，得先手动清理一波历史债务。

改完之后，本地跑 npm run lint:css:fix 能自动修好大部分格式问题，CI 里跑 lint:css 确保不合规代码无法合入。虽然还有个别文件因为用了非常规 mixin 报错，但加个 /* stylelint-disable-next-line */ 临时绕过也无大碍——毕竟团队优先级是推进功能，不是追求 100% lint clean。

以上是我踩坑后的总结，如果你有更好的方案欢迎评论区交流

说实话，StyleLint 的生态有点碎片化，不同版本、不同预处理器、不同框架组合起来容易出幺蛾子。但只要抓住核心：明确解析器（customSyntax）、选对 config 包、忽略非样式文件，基本就能稳住。这个方案在我手头三个项目里都跑通了，包括一个用 SCSS + Tailwind 混写的复杂后台系统。如果你也在集成时遇到诡异报错，不妨先检查下 postcss 和 postcss-scss 是否都装了，以及配置里的 customSyntax 是否指向正确。欢迎留言讨论！