如何使用 Stylelint 对 CSS 进行 Lint 检查

杂乱的 CSS 写起来容易，维护起来却很难。拼写错误的属性、重复的选择器以及不一致的规范会在代码评审中悄然漏过，逐渐积累成技术债务。Stylelint 通过自动捕获错误并强制执行规范来解决这个问题——在它们进入生产环境之前。

本指南涵盖了你今天就能让 Stylelint CSS Lint 检查在项目中跑起来所需的一切。

什么是 Stylelint，为什么它应该出现在你的工作流中？

Stylelint 是一款拥有超过 100 条内置规则的 CSS Linter，被 Google 和 GitHub 等团队所信任。它会对 CSS 文件进行静态分析，并报告问题——无效语法、未知属性、重复选择器以及违反规范的情况——而无需运行代码。

有一个重要的区分：Stylelint 处理的是代码质量，而不是格式化。它不会与 Prettier 在空格或分号问题上争锋。两款工具是互补的。Prettier 负责格式化，而 Stylelint 强制执行正确性与一致性。两者都该使用。

安装 Stylelint：两种入门方式

Stylelint 需要较新的 Node.js 版本（最新版本要求 Node 20.19.0 或更高），因此请确保你的环境是最新的。

方式一：自动化搭建（推荐）

使用 Stylelint 对 CSS 进行 Lint 检查最快的方式是 create 命令：

npm create stylelint@latest

它会生成一份配置文件并自动安装 stylelint-config-standard。该命令同样支持 pnpm、Yarn 和 Bun：

pnpm create stylelint
bun create stylelint

方式二：手动搭建 Stylelint

如果你希望完全掌控，可以自行安装依赖：

npm add -D stylelint stylelint-config-standard

然后在项目根目录创建一个 stylelint.config.mjs 文件：

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"]
};

.mjs 扩展名表示使用 ESM——现代模块格式。Stylelint 支持 ESM 配置，也是当前推荐的方式。

在 CSS 文件上运行 Stylelint

安装完成后，对所有 CSS 文件运行 Stylelint：

npx stylelint "**/*.css"

对于任何违规情况，你都会看到类似下面的输出：

src/main.css
  12:3  ✖  Unexpected duplicate selector ".btn"   no-duplicate-selectors
  24:5  ✖  Unknown property "colour"              property-no-unknown

要自动修复可修复的问题，添加 --fix 参数：

npx stylelint "**/*.css" --fix

并非所有规则都支持自动修复，但相当多的规则支持。--fix 会在可能的情况下应用安全的修复，但它不会解决所有问题。

配置 Stylelint CSS Lint 规则

stylelint-config-standard 是一个稳健的基线。你可以在配置中扩展它并覆盖特定规则：

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "selector-id-pattern": null  // disable a rule
  }
};

规则接受 true 启用，null 禁用，或使用数组来配置严重级别：

"color-no-invalid-hex": [true, { severity: "warning" }]

这在向已有代码库引入 Stylelint 时非常有用——警告让你能在不立刻阻塞构建的情况下审计问题。

在 package.json 中添加 Lint 脚本

通过一个 npm 脚本将 Stylelint 接入你的工作流：

{
  "scripts": {
    "lint:css": "stylelint \"**/*.css\""
  }
}

使用 npm run lint:css 运行。在此基础上，你可以借助 lint-staged 和 Husky 将其集成到 CI 流水线或预提交钩子中。

CSS Lint 最佳实践

• 从 stylelint-config-standard 开始 —— 它反映了当前的 CSS 最佳实践，并且持续维护。
• 在遗留代码上引入 Stylelint 时，先使用警告再升级为错误。
• 忽略生成的文件，通过添加 .stylelintignore 文件实现（类似于 .gitignore）。
• 与 Prettier 搭配 —— 不要尝试用 Stylelint 来做格式化。
• 在 CI 中运行 —— 仅依赖本地机器的 Lint 检查会被跳过。

总结

Stylelint 的搭建只需大约五分钟，立即就能在捕获错误和保持代码一致性方面带来回报。安装它，扩展 stylelint-config-standard，添加一个脚本，然后运行它。整套配置就这些。其他的一切——自定义规则、SCSS 支持、IDE 集成——都建立在这个基础之上。

常见问题

Stylelint 能与 SCSS、Less 或 CSS-in-JS 配合使用吗？

可以。Stylelint 通过自定义语法（如 `postcss-scss` 或 `postcss-less`）支持 SCSS、Less 以及其他类 CSS 语法。对 CSS-in-JS 的支持取决于具体的库，需要通过 `customSyntax` 选项配置相应的自定义语法包。

如果我已经在用 Prettier，还需要使用 Stylelint 吗？

需要，它们解决的是不同的问题。Prettier 负责格式化你的代码，处理空白、换行和引号风格。Stylelint 捕获代码质量问题，例如无效属性、重复选择器和违反规范的情况。现代 Stylelint 已专门移除了其样式相关规则，以避免与 Prettier 重叠，因此两款工具可以协同工作而互不冲突。

如何在预提交钩子中只对变更的文件运行 Stylelint？

使用 lint-staged 配合 Husky。在 package.json 中配置 lint-staged，对暂存的 CSS 文件运行 stylelint --fix，然后添加一个调用 lint-staged 的 Husky 预提交钩子。这样只会对即将提交的文件进行 Lint 检查，即便在大型仓库中也能保持钩子的快速执行，同时防止有问题的 CSS 进入主分支。

Stylelint 能与编辑器集成以提供实时反馈吗？

可以。VS Code 有官方的 Stylelint 扩展，可在你输入时高亮问题，并能在保存时修复它们。WebStorm 以及其他 JetBrains IDE 内置了 Stylelint 支持。其他编辑器可能有社区维护的集成。相比手动运行 CLI，编辑器集成显著缩短了反馈循环。