Back

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

OpenReplay Team

May 4, 2026 · 2 min read

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

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

关键要点

Stylelint 通过静态分析捕获 CSS 错误并强制执行规范，内置超过 100 条规则。
它处理的是代码质量，而非格式化，因此能与 Prettier 自然搭配，而非相互冲突。
最快的搭建方式是 npm create stylelint@latest，它会生成一份配置并安装 stylelint-config-standard。
规则可以启用、禁用或降级为警告——在已有代码库中引入 Stylelint 时非常有用。
将其接入 npm 脚本和 CI 流水线，确保 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 通过自定义语法（如 `postcss-scss` 或 `postcss-less`）支持 SCSS、Less 以及其他类 CSS 语法。对 CSS-in-JS 的支持取决于具体的库，需要通过 `customSyntax` 选项配置相应的自定义语法包。

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

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

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

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.