Stylelint：CSS 规则、custom syntax 与样式门禁

高谷深陵大约 5 分钟约 1633 字

Stylelint 样式语法与规则裁决CSS 与扩展语法先进入正确 custom syntax，再由共享配置、插件和规则生成可审计结果。高清原图

Stylelint 先要读懂文件，才能谈规则

Stylelint 检查 CSS 及通过 custom syntax/processor 支持的样式代码。普通 CSS、SCSS、Vue SFC、CSS-in-JS 不是同一语法入口；只把后缀加入 glob，可能得到大量伪语法错误，也可能让嵌入样式根本未被提取。确定性排版由 Prettier负责，JavaScript 语义由 ESLint负责。

本文实验锁定 Stylelint 17.14.1。当前主版本的规则与 Node.js 支持以官方 Release和迁移指南为准；共享配置、插件和 custom syntax 还有各自 peer dependency。版本只作为验证基线。

安装核心与标准配置

npm install --save-dev --save-exact stylelint@17.14.1 stylelint-config-standard
npm ci
npm exec -- stylelint --version
npm ls stylelint stylelint-config-standard

普通 CSS 的 stylelint.config.mjs：

/** @type {import("stylelint").Config} */
export default {
  extends: ["stylelint-config-standard"],
  ignoreFiles: ["dist/**", "coverage/**", "generated/**"],
  reportDescriptionlessDisables: true,
  reportInvalidScopeDisables: true,
  reportNeedlessDisables: true,
  reportUnscopedDisables: true,
  rules: {
    "color-no-invalid-hex": true,
    "declaration-block-no-duplicate-properties": true,
  },
};

共享配置提供起点，不是永久政策。项目覆盖规则要写清原因和 owner；升级共享配置时比较最终规则集合与问题差异，不能只看核心 Stylelint 版本。

custom syntax 是解析边界

SCSS、Vue、Svelte 或 CSS-in-JS 需要对应的受支持 custom syntax 与共享配置，并用 overrides 限定：

export default {
  extends: ["stylelint-config-standard"],
  overrides: [
    {
      files: ["**/*.scss"],
      customSyntax: "postcss-scss",
      extends: ["stylelint-config-standard-scss"],
    },
    {
      files: ["**/*.vue"],
      customSyntax: "postcss-html",
    },
  ],
};

这些包必须进入项目依赖并锁版本。为每种文件类型保留一个应通过样例和一个应失败样例；核心、custom syntax、共享配置或框架升级后全套复跑。若解析器只能看见 Vue 模板而没有提取 <style>，绿灯不代表样式被检查。

ignore 要能证明没有吞掉源码

大量排除放在 .stylelintignore：

dist/
coverage/
generated/
vendor/

配置中的 ignoreFiles 适合少量稳定路径。CI 固定工作目录，Windows 与 Linux 的大小写和路径分隔差异进入验证。文件没有被检查时使用详细输出与一个故意违规对照，不靠“命令执行很快”判断 glob 是否为空。

正反样例与非零退出码

.card {
  color: #12zz99;
  display: block;
  display: flex;
}

执行：

npm exec -- stylelint .quality-smoke/stylelint-bad.css

预期 color-no-invalid-hex 与重复属性规则命中，退出码非零。修正颜色并删除无效重复后，同一命令通过。若报告出现但 CI 绿灯，检查 shell 管道、|| true 和包装脚本；若没有报告，检查 glob、ignore、配置查找与 custom syntax。

项目脚本分开检查和修复：

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

glob 由引号交给 Stylelint 处理，降低不同 shell 展开差异。CI 只运行检查；--fix 在开发者或独立修复提交执行，并在前后查看 Git diff。

Stylelint：CSS 规则、custom syntax 与样式门禁

Stylelint 先要读懂文件，才能谈规则

安装核心与标准配置

custom syntax 是解析边界

ignore 要能证明没有吞掉源码

正反样例与非零退出码

disable 注释是例外记录

与 Prettier 的冲突只保留一个 owner

插件、formatter 与报告边界

性能、缓存与多包仓库

升级与回滚