跳到正文

我所理解的 Lint 最佳实践(2):使用 Stylelint 而不是 @eslint/css 检查样式

我所理解的 Lint 最佳实践

  1. 把项目约定写成 ESLint 护栏
  2. 使用 Stylelint 而不是 @eslint/css 检查样式(当前)
  3. 用 ESLint 约束 Nuxt 的自动导入
  4. 用 ESLint 判断 Vue 组件的根 Block
  5. 用 ESLint 守住 Composable 的模块边界
  6. 给 Nuxt 模块级 Composable 补上 SSR 护栏
  7. 用组件调用图检查可选 props
  8. 用 ESLint 检查源码文件的目录归属
  9. 让 Lint 规则覆盖所有适用的代码位置

主题已经用 ESLint 检查 Vue 模板和 TypeScript。ESLint 有了 CSS 语言插件之后,样式也可以交给同一个命令。不过这里的输入除了普通 .css,还有 Vue <style scoped lang="scss">、SCSS 的选择器拼接,以及需要读取 UnoCSS 配置的 @apply 规则。把同一个例子交给两套工具,首先要看规则实际能读到什么。

先看原文件的语法

@eslint/css 用 CSSTree 解析 CSS,能为标准选择器和属性值提供细粒度的语法树。普通 CSS 中的 @apply p-2 p-4 也能通过 Atrule 节点取到参数。它的 customSyntax 可以扩充 lexer 对指令、属性和值类型的认识。tolerant 会允许部分解析错误,并把无法细分的片段保留为 Raw。

把包含 $pad 和 &__title 的 SCSS 直接交给 @eslint/css 2.0.1,严格模式报解析错误。宽容模式会保留 &__title 所在的片段,但其中的 @apply 随整段进入 Raw,规则收不到 Atrule。Less 的 @ink: red 也会在严格模式报错,宽容模式还能读到后面花括号中的 color 声明。把花括号省略的 Stylus 样例交给宽容模式,则没有可访问的声明节点。只看退出码,很容易把「解析继续了」当作「规则覆盖了」。

Stylelint 用 PostCSS 的 customSyntax 切换原文件的解析方式。SCSS 用 postcss-scss,Less 用 postcss-less,Stylus 可以试 postcss-styl。在上面的 Less 和 Stylus 样例中,Stylelint 都能把声明交给规则。Vue 项目还可以用 postcss-html 提取 <style>,保留诊断在 .vue 中的原始位置。能解析变量或 mixin 与能计算它们展开后的样式是两回事,例如 Stylelint 的 SCSS 专用规则 检查 SCSS 源码,展开后的样式仍由编译器决定。

CSS-in-JS 要区分模板字符串和对象

「Stylelint 对 CSS-in-JS 的支持有限」这段说明出自社区的 eslint-plugin-css。它面向 Vue、JSX 和部分 styled-components 样式对象,与 ESLint 官方用于样式表的 @eslint/css 是两个包。

旧的 @stylelint/postcss-css-in-js 已停止维护。特定问题陆续修复了,例如嵌入样式块的 no-invalid-position-declaration 漏报。今天可以用 postcss-styled-syntax 等适配器检查特定的带标签模板字符串。

用 Stylelint 18.0.0 和 postcss-styled-syntax 0.7.4 跑同一个 TSX 文件,color-no-invalid-hex 报出了 styled.div 模板里的 #xyz。同样的值写进 JSX 的 style={{ color: '#xyz' }},或传给 styled.div({ color: '#xyz' }),这套配置都没有报。要判断项目的覆盖范围,可以把自己实际使用的几种样式写法放在同一个文件里,各留一个必然触发规则的反例。

对象形式包括 React 的 style、Vue 的 :style,也包括 CSS-in-JS 库的对象 API。社区的 eslint-plugin-css 可以在支持的入口识别样式对象,检查重复属性等问题。能取得具体对象时,也可以用 postcss-js 把它转成 PostCSS 节点,再做 CSS 检查。从任意 JSX 或 Vue 源文件中定位对象、处理展开与动态值、把诊断映射回原文件,则需要另一层分析。

组件的固定样式放在样式表或 <style> 里,媒体查询、伪类和状态可以在同一个选择器附近维护。值来自拖动坐标、进度或用户主题时,可以用内联样式传 CSS 自定义属性,再由样式表消费。Vue SFC 也能用 CSS v-bind() 引用组件里的动态值。

写规则时,AST 与运行协议各管一层

检查 @apply 参数时,PostCSS 的 root.walkAtRules('apply', …) 可以直接拿到 node.params。在 @eslint/css 中,可以访问 Atrule,再用 sourceCode.getText(node.prelude) 取回参数。规则要分析标准选择器、函数或数值单位时,CSSTree 的 AST 已把这些成分拆成节点。PostCSS 通常把 selector 和 value 保留为字符串,需要细读时再用专门的解析器。

p-2 p-4 的冲突要用项目的 UnoCSS 配置解析,知道两个类实际写了哪些属性。Stylelint 的异步规则可以直接 await 配置和生成器。用 async Atrule() 写的 ESLint 样例在回调结束前就返回了诊断结果。UnoCSS 的官方 ESLint 插件用 synckit 把异步 worker 封装成同步调用。对只需要检查样式块的规则,Stylelint 可以直接使用异步接口。

同一批 CSS 的检查耗时

160 个普通 CSS 文件,每个文件有 48 个包含常见属性的规则块和一个空块,总计约 0.92 MB。两边各启用一条空块规则,每轮都确认报出 160 个空块。环境为 Windows、i5-14600K、Node.js 26.12.0,使用 Node API,关闭磁盘缓存、修复和 ESLint 多线程。版本为 ESLint 10.13.0、@eslint/css 2.0.1 和 Stylelint 18.0.0。

检查 160 个普通 CSS 文件的耗时中位数。新进程 ESLint 513 ms、Stylelint 331 ms。同进程预热后 ESLint 176.5 ms、Stylelint 65.5 ms。

这批输入上 Stylelint 更快。测试覆盖普通 CSS 的解析和一条轻量规则,Vue 提取、完整规则集、UnoCSS 生成与编辑器保存延迟各有自己的成本。样本大小、配置和逐轮数据见性能对照记录弹窗。

编辑器、规则测试与迁移

两边都能检查生效配置、缓存结果、输出 JSON 诊断和自动修复。自研规则可以分别用 ESLint 的 RuleTester 和 stylelint-test-rule-node 验证,也可以用 stylelint.lint() 测真正的 Vue 样式块和位置。ESLint 有 --stats 查看每条规则的耗时、--inspect-config 查看配置的应用过程,以及 bulk suppressions 来逐步处理已有违规。Stylelint 的选项可以要求禁用注释指出具体规则并说明原因,也能报告过时的豁免。

Stylelint 的样式规则和适配器更齐全。npm 在 2026 年 11 月 2 日至 8 日记录了约 1,410 万次 Stylelint 下载和 73 万次 @eslint/css 下载。这个数字包含 CI 和间接安装,可以用来观察两者的使用规模。

纯 CSS 项目如果只需要 @eslint/css 已有的几项检查,可以让 CSS 跟脚本共用 ESLint 的配置和 CLI。这里让 ESLint 检查脚本和模板,Stylelint 检查 CSS、SCSS 和 Vue 样式块,再由一个项目命令运行两边。UnoCSS 的专项检查也接在样式侧,见《利用 Lint 规范 UnoCSS 写法》。

ESLint 的语言插件与 processor

ESLint 的 flat config 可以为不同文件指定 language。语言插件提供解析器、节点遍历和相关规则,ESLint 负责配置、报告和修复。官方有 @eslint/json(JSON、JSONC、JSON5)、@eslint/markdown(CommonMark、GFM)、@eslint/css 和 @eslint/shell(Bash、POSIX sh、mksh)。社区也有 HTML、YAML、TOML 的语言插件。

processor 则负责从容器提取片段。例如 Markdown 正文可以用 Markdown 规则检查,代码围栏里的 JavaScript 则提取后交给 JavaScript 规则。接入 Vue 样式同样要分别确认谁负责提取、谁能解析 SCSS、诊断和修复怎样回到 .vue 原文件。

普通 CSS 的 Lint 性能对照

打开原文件 css-lint-benchmark.json

样本使用 display: grid、gap、padding-inline、带 fallback 的 CSS 变量和 border-radius,末尾追加一个空块。ESLint 用 css/no-empty-blocks,Stylelint 用 block-no-empty。新进程测试按轮交替启动,计时包括文件读取、加载依赖和 Node 进程启动。进程内各跑 8 轮,前 2 轮用来预热。文件系统缓存由操作系统管理。

逐轮耗时与环境
{
  "node": "26.12.0",
  "system": "win32 10.0.26300 x64",
  "cpu": "Intel(R) Core(TM) i5-14600K",
  "fileCount": 160,
  "blocksPerFile": 48,
  "bytes": 916370,
  "expected": 160,
  "cold": {
    "eslint": [
      546,
      513,
      510,
      526,
      480
    ],
    "stylelint": [
      361,
      331,
      331,
      352,
      317
    ]
  },
  "warm": {
    "eslint": [
      272,
      163,
      171,
      179,
      172,
      177,
      176,
      181
    ],
    "stylelint": [
      182,
      73,
      70,
      67,
      92,
      64,
      63,
      61
    ]
  },
  "summaries": {
    "eslint": {
      "coldMedian": 513,
      "warmMedian": 176.5,
      "warmMin": 171,
      "warmMax": 181
    },
    "stylelint": {
      "coldMedian": 331,
      "warmMedian": 65.5,
      "warmMin": 61,
      "warmMax": 92
    }
  }
}