Stylelint logo

Stylelint

CSS/SCSS/Less 等样式文件的现代化检查工具，帮助团队保持样式代码的一致性和避免错误

代码质量CSSLinter样式检查

Stylelint 是 CSS/SCSS/Less 等样式文件的现代化检查工具，提供 100+ 内置规则，帮助团队保持样式代码一致性并避免错误，是前端工程化 CSS 质量保障的事实标准。

访问官网

Stylelint

CSS/SCSS/Less 等样式文件的现代化检查工具，帮助团队保持样式代码的一致性和避免错误

技术简介说明

Stylelint 是一个强大的、现代化的 CSS linter 工具，用于检查样式代码并确保其符合约定的编码规范。它支持多种样式语法，包括 CSS、SCSS、Sass、Less 等，提供了超过 100 个内置规则，能够检测语法错误、遵循代码约定、避免样式冲突等问题。

Stylelint 的设计理念是高度可配置和插件化，允许团队根据项目需求自定义规则集合。它与 ESLint 类似，但专注于样式文件，是现代前端工程化中不可或缺的质量保障工具。

基本信息

属性说明
当前版本16.25.0（2025 年 10 月发布）
开发状态活跃维护，v17 开发中
开源协议MIT License
GitHubstylelint/stylelint
官网https://stylelint.io
npmstylelint
支持语法CSS、SCSS、Sass、Less、SugarSS
Node.js 要求Node.js 18.12.0+
首次发布2015 年
维护状态活跃开发，社区驱动

快速上手

安装

# 使用 npm 安装
npm install stylelint --save-dev
 
# 使用 pnpm 安装（推荐）
pnpm add -D stylelint
 
# 使用 yarn 安装
yarn add -D stylelint

基础配置

创建 .stylelintrc.json 或 stylelint.config.js 配置文件：

{
  "extends": "stylelint-config-standard",
  "rules": {
    "color-no-invalid-hex": true,
    "font-family-no-duplicate-names": true,
    "declaration-block-no-duplicate-properties": true,
    "block-no-empty": true,
    "comment-no-empty": true,
    "no-duplicate-selectors": true
  }
}

最小示例

package.json 中添加 scripts：

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

示例样式文件 src/styles/example.css：

/* 错误示例 - Stylelint 会检测出问题 */
.error {
  color: #fff;  /* 应该使用小写 */
  font-family: Arial, Arial;  /* 重复的字体 */
  background: #fff
  margin: 10px;
  margin: 20px;  /* 重复的属性 */
}
 
/* 正确示例 */
.correct {
  color: #fff;
  font-family: Arial, sans-serif;
  background: #fff;
  margin: 10px;
}

运行检查：

# 检查样式文件
pnpm lint:css
 
# 自动修复可修复的问题
pnpm lint:css:fix

核心概念与架构

核心架构

Stylelint 采用插件化架构设计，主要由以下组件构成：

  1. 解析器（Parser）

    • 使用 postcss 作为默认解析器
    • 支持自定义解析器处理不同的预处理器语法
    • postcss-scss 处理 SCSS 语法
    • postcss-less 处理 Less 语法

  2. 规则引擎（Rule Engine）

    • 内置 100+ 规则
    • 规则分为多个类别：可能的问题、可限制的功能、字体、颜色、选择器等
    • 每条规则独立运行，互不干扰

  3. 配置系统（Configuration System）

    • 支持继承和扩展配置
    • 支持 extends、plugins、rules、overrides 等配置项
    • 支持动态配置和条件规则

  4. 插件系统（Plugin System）

    • 允许社区开发自定义规则
    • 插件可以打包发布到 npm
    • 官方维护 stylelint-order 等核心插件

规则分类

Stylelint 的规则按功能分为以下类别：

  • 可能的问题（Possible errors）：检测语法错误和潜在问题
  • 可限制的功能（Limit language features）：限制某些 CSS 特性的使用
  • 字体（Font）：字体相关规则
  • 颜色（Color）：颜色格式和命名规则
  • 选择器（Selector）：选择器命名和结构规则
  • 属性（Property）：属性命名和值规则
  • 声明（Declaration）：声明块相关规则
  • 值（Value）：属性值相关规则
  • 媒体查询（Media query）：媒体查询相关规则
  • 注释（Comment）：注释相关规则
  • 通用（General）：通用规则

核心特性

1. 100+ 内置规则

提供全面的规则集合，覆盖现代 CSS 的各个方面：

{
  "rules": {
    "color-no-invalid-hex": true,
    "color-named": "never",
    "color-hex-length": "short",
    "font-family-no-duplicate-names": true,
    "function-calc-no-unspaced-operator": true,
    "string-no-newline": true,
    "unit-no-unknown": true,
    "property-no-unknown": true,
    "declaration-block-no-duplicate-properties": true,
    "block-no-empty": true,
    "selector-pseudo-class-no-unknown": true,
    "selector-pseudo-element-no-unknown": true,
    "selector-type-no-unknown": true,
    "media-feature-name-no-unknown": true,
    "comment-no-empty": true,
    "no-duplicate-selectors": true,
    "no-empty-source": true
  }
}

2. 自动修复功能

支持自动修复大量规则问题：

# 自动修复可修复的问题
stylelint "src/**/*.css" --fix
 
# 在 webpack 中启用自动修复
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  ['stylelint', { fix: true }]
                ]
              }
            }
          }
        ]
      }
    ]
  }
}

3. 批量抑制功能（实验性）

v16.25.0 新增的实验性功能，支持批量抑制规则警告：

/* stylelint-disable-next-line color-no-invalid-hex */
.color { color: #FFF; }
 
/* stylelint-disable */
.ignored-block {
  color: #FFF;
  background: red;
}
/* stylelint-enable */
 
/* 针对特定文件抑制 */
/* stylelint-disable plugin/rule-name */

4. 高度可配置

灵活的配置系统支持多种配置方式：

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-recommended-scss"
  ],
  "plugins": [
    "stylelint-order",
    "stylelint-scss"
  ],
  "rules": {
    "indentation": 2,
    "color-hex-case": "lower",
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]+$"
  },
  "overrides": [
    {
      "files": ["**/*.scss"],
      "customSyntax": "postcss-scss",
      "rules": {
        "scss/at-rule-no-unknown": true
      }
    },
    {
      "files": ["**/*.less"],
      "customSyntax": "postcss-less",
      "rules": {
        "less/color-no-invalid-hex": true
      }
    }
  ]
}

5. 预处理器支持

完整支持主流 CSS 预处理器：

# 安装预处理器支持
pnpm add -D postcss-scss postcss-less
 
# .stylelintrc.json
{
  "customSyntax": "postcss-scss",
  "rules": {
    "scss/at-rule-no-unknown": true,
    "scss/selector-no-redundant-nesting-selector": true
  }
}

6. CSS Baseline 支持

2025 年 4 月新增对 CSS Baseline 的支持，与 Web Platform 的 Baseline 计划对齐：

{
  "rules": {
    "property-no-unknown": [
      true,
      {
        "ignoreProperties": ["/^my-custom-/"]
      }
    ],
    "value-no-vendor-prefix": [
      true,
      {
        "ignoreValues": ["box"]
      }
    ]
  }
}

7. 现代化的配置格式

支持 JavaScript 配置文件，提供更强大的配置能力：

// stylelint.config.js
module.exports = {
  extends: ['stylelint-config-standard'],
  rules: {
    'color-hex-case': 'lower',
    'indentation': 2,
    'max-nesting-depth': 3,
    'selector-max-specificity': '1,2,1',
    'selector-max-compound-selectors': 3,
    'selector-max-id': 0,
    'selector-max-universal': 0,
    'declaration-no-important': true,
    'font-weight-notation': 'numeric',
    'number-max-precision': 4,
    'time-min-milliseconds': 100,
    'unit-disallowed-list': ['pt', 'cm', 'mm'],
    'length-zero-no-unit': true,
    'value-keyword-case': 'lower',
    'custom-property-pattern': '^my-[a-z][a-zA-Z0-9]+$',
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$',
    'keyframes-name-pattern': '^[a-z][a-zA-Z0-9]+-$'
  }
}

8. 丰富的报告格式

支持多种输出格式，便于集成到不同的工作流：

# JSON 格式输出
stylelint "src/**/*.css" --formatter json
 
# 紧凑格式输出
stylelint "src/**/*.css" --formatter compact
 
# Unix 格式输出
stylelint "src/**/*.css" --formatter unix
 
# 详细格式输出
stylelint "src/**/*.css" --formatter verbose
 
# 自定义报告器
stylelint "src/**/*.css" --formatter ./my-formatter.js

9. IDE 集成

主流编辑器都有 Stylelint 插件支持：

// VS Code settings.json
{
  "stylelint.enable": true,
  "stylelint.validate": [
    "css",
    "less",
    "postcss",
    "scss",
    "sugarss"
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": true
  }
}

10. Git 集成

与 Git 工作流无缝集成：

# 使用 lint-staged 在提交前检查
// package.json
{
  "lint-staged": {
    "*.{css,scss,less}": [
      "stylelint --fix",
      "git add"
    ]
  }
}
 
# 使用 husky 添加 pre-commit hook
// .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
 
pnpm lint-staged

生态图

官方维护的配置包

# 推荐配置
pnpm add -D stylelint-config-recommended
 
# 标准配置（包含更多规则）
pnpm add -D stylelint-config-standard
 
# 空配置（作为基础）
pnpm add -D stylelint-config-clean-order

预处理器插件

# SCSS 支持
pnpm add -D stylelint-scss postcss-scss
 
# Less 支持
pnpm add -D stylelint-less postcss-less
 
# SugarSS 支持
pnpm add -D postcss-sugarss

社区插件

# 属性排序
pnpm add -D stylelint-order
 
# 防御性 CSS
pnpm add -D stylelint-plugin-defensive-css
 
# CSS 模块
pnpm add -D stylelint-css-modules
 
# 可访问性检查
pnpm add -D stylelint-a11y
 
# 最佳实践
pnpm add -D stylelint-plugin-best-practices
 
# BEM 命名规范
pnpm add -D stylelint-selector-bem-pattern
 
# 高性能 CSS
pnpm add -D stylelint-plugin-high-performance-css
 
# 颜色对比度检查
pnpm add -D stylelint-color contrast

流行的预设配置

# Airbnb 风格
pnpm add -D stylelint-config-airbnb
 
# WordPress 风格
pnpm add -D stylelint-config-wordpress
 
# Shopify 风格
pnpm add -D @shopify/stylelint-plugin
 
# GitHub 风格
pnpm add -D stylelint-config-github
 
# Prettier 集成
pnpm add -D stylelint-config-prettier

构建工具集成

# Webpack
pnpm add -D stylelint-webpack-plugin
 
# Vite
pnpm add -D vite-plugin-stylelint
 
# Gulp
pnpm add -D gulp-stylelint
 
# PostCSS
pnpm add -D postcss-stylelint

完整生态示例配置

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-recommended-scss",
    "stylelint-config-clean-order"
  ],
  "plugins": [
    "stylelint-scss",
    "stylelint-order",
    "stylelint-plugin-defensive-css"
  ],
  "customSyntax": "postcss-scss",
  "rules": {
    "order/properties-order": [
      [
        "content",
        "display",
        "position",
        "top",
        "right",
        "bottom",
        "left",
        "flex",
        "grid",
        "width",
        "height",
        "margin",
        "padding",
        "border",
        "background",
        "color",
        "font",
        "text",
        "line-height",
        "transform",
        "transition",
        "animation"
      ]
    ],
    "plugin/defensive-css": [
      true,
      {
        "accidental-hover": true,
        "background-repeat": true,
        "flex-wrap": true,
        "scroll-chaining": true,
        "scroll-lock": true
      }
    ]
  }
}

适用场景

1. 大型团队协作项目

在多人协作的项目中，Stylelint 确保所有开发者遵循统一的样式编码规范，减少代码审查成本：

{
  "extends": "stylelint-config-standard",
  "rules": {
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]+$",
    "custom-property-pattern": "^[a-z][a-zA-Z0-9-]+$",
    "max-nesting-depth": 3,
    "selector-max-specificity": "1,2,1",
    "declaration-no-important": true,
    "color-named": "never",
    "font-family-name-quotes": "always-where-recommended"
  }
}

2. 设计系统集成

确保设计系统中的样式组件保持一致性：

{
  "rules": {
    "custom-property-pattern": "^ds-[a-z][a-zA-Z0-9-]+$",
    "selector-class-pattern": "^ds-[a-z][a-zA-Z0-9-]+$",
    "color-no-hex": true,
    "unit-disallowed-list": ["px", "em"],
    "unit-allowed-list": ["rem", "vh", "vw", "%"]
  }
}

3. 组件库开发

为组件库提供统一的样式规范：

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-recommended-scss"
  ],
  "plugins": ["stylelint-scss"],
  "customSyntax": "postcss-scss",
  "rules": {
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]+$",
    "scss/at-rule-no-unknown": true,
    "scss/selector-no-redundant-nesting-selector": true,
    "no-descending-specificity": true,
    "selector-max-universal": 0
  }
}

4. 遗留代码迁移

逐步改进遗留项目的样式质量：

{
  "extends": "stylelint-config-recommended",
  "rules": {
    "color-no-invalid-hex": true,
    "font-family-no-duplicate-names": true,
    "property-no-unknown": true,
    "declaration-block-no-duplicate-properties": true,
    "block-no-empty": true
  },
  "ignoreFiles": [
    "node_modules/**",
    "dist/**",
    "legacy/**"
  ]
}

5. CSS-in-JS 项目

检查 styled-components、emotion 等 CSS-in-JS 方案：

# 安装相关依赖
pnpm add -D stylelint stylelint-config-styled-components
{
  "extends": "stylelint-config-styled-components",
  "processors": [
    "stylelint-processor-styled-components"
  ],
  "rules": {
    "no-empty-source": null,
    "no-missing-end-of-source-newline": null
  }
}

6. 性能优化项目

检测和避免性能问题的样式代码：

{
  "rules": {
    "selector-max-universal": 0,
    "selector-max-type": 3,
    "selector-max-attribute": 2,
    "selector-max-class": 3,
    "selector-max-id": 0,
    "selector-max-pseudo-class": 3,
    "selector-max-combinators": 3,
    "selector-max-compound-selectors": 3,
    "max-nesting-depth": 3,
    "no-descending-specificity": true,
    "declaration-block-no-redundant-longhand-properties": true
  }
}

7. 可访问性优先项目

确保样式代码符合可访问性要求：

pnpm add -D stylelint-a11y
{
  "extends": "stylelint-config-standard",
  "plugins": ["stylelint-a11y"],
  "rules": {
    "a11y/media-prefers-reduced-motion": true,
    "a11y/no-outline-none": true,
    "a11y/selector-pseudo-class-focus": true,
    "a11y/content-no-quotes": true
  }
}

开发与工程化

与构建工具集成

Webpack 集成

// webpack.config.js
const StylelintPlugin = require('stylelint-webpack-plugin')
 
module.exports = {
  plugins: [
    new StylelintPlugin({
      files: 'src/**/*.{css,scss,less}',
      fix: true,
      cache: true,
      emitWarning: true,
      emitError: false,
      failOnError: false,
      quiet: false
    })
  ]
}

Vite 集成

// vite.config.js
import { defineConfig } from 'vite'
import stylelint from 'vite-plugin-stylelint'
 
export default defineConfig({
  plugins: [
    stylelint({
      include: ['src/**/*.css', 'src/**/*.scss'],
      fix: true,
      emitErrorAsWarning: true
    })
  ]
})

Turborepo 集成

// turbo.json
{
  "tasks": {
    "lint:css": {
      "inputs": [
        "src/**/*.css",
        "src/**/*.scss",
        "src/**/*.less",
        ".stylelintrc.json"
      ],
      "outputs": []
    }
  }
}

CI/CD 集成

# .github/workflows/stylelint.yml
name: Stylelint
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
 
jobs:
  stylelint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Run Stylelint
        run: pnpm lint:css
      
      - name: Report coverage
        if: github.event_name == 'pull_request'
        run: |
          pnpm lint:css --formatter json > stylelint-report.json

Git Hooks 集成

# 安装 husky 和 lint-staged
pnpm add -D husky lint-staged
 
# 初始化 husky
pnpm exec husky init
 
# 配置 pre-commit hook
echo '#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
 
pnpm exec lint-staged' > .husky/pre-commit
// package.json
{
  "lint-staged": {
    "*.{css,scss,less}": [
      "stylelint --fix",
      "git add"
    ]
  }
}

编辑器集成配置

VS Code

// .vscode/settings.json
{
  "stylelint.enable": true,
  "stylelint.validate": [
    "css",
    "less",
    "postcss",
    "scss",
    "sugarss"
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": "explicit"
  },
  "stylelint.configOverrides": {
    "customSyntax": "postcss-scss"
  }
}

WebStorm/IDEA

// .idea/stylelint.json (自动生成)
{
  "enabled": true,
  "configLocation": ".stylelintrc.json"
}

性能与安全

性能优化

缓存机制

// stylelint.config.js
module.exports = {
  // 启用缓存
  cache: true,
  cacheLocation: './node_modules/.cache/stylelint',
  
  // 只检查变更的文件
  ignoreFiles: [
    'node_modules/**',
    'dist/**',
    'build/**',
    'coverage/**'
  ]
}

并行处理

# 使用 --concurrency 参数控制并发数
stylelint "src/**/*.css" --concurrency 4
 
# 在大型项目中只检查变更文件
stylelint $(git diff --name-only --diff-filter=d HEAD | grep -E '\.(css|scss|less)$')

增量检查

# 只检查未暂存的文件
stylelint $(git diff --name-only --diff-filter=d | grep -E '\.(css|scss|less)$')
 
# 只检查暂存的文件
stylelint $(git diff --cached --name-only --diff-filter=d | grep -E '\.(css|scss|less)$')

安全考虑

避免敏感信息泄露

{
  "rules": {
    "comment-word-disallowed-list": [
      "password",
      "secret",
      "token",
      "api-key",
      "private"
    ]
  }
}

防止 CSS 注入

{
  "rules": {
    "function-disallowed-list": ["url"],
    "value-no-vendor-prefix": true,
    "property-no-vendor-prefix": true,
    "selector-no-vendor-prefix": true
  }
}

依赖安全

# 定期审计依赖
pnpm audit
 
# 使用安全的插件来源
# 只使用官方维护或社区知名的插件

内存管理

// stylelint.config.js
module.exports = {
  // 大项目建议启用缓存
  cache: true,
  
  // 限制并发数以控制内存使用
  // 通过 CLI 参数 --concurrency 控制
  
  // 排除不需要检查的文件
  ignoreFiles: [
    'node_modules/**',
    '**/*.min.css',
    '**/vendor/**',
    '**/dist/**'
  ]
}

技术对比

与 ESLint 对比

特性StylelintESLint
检查对象CSS/SCSS/Less 等样式文件JavaScript/TypeScript
解析器PostCSSEspree/TypeScript
规则数量100+ 内置规则300+ 内置规则
自动修复支持部分规则支持大量规则
插件生态丰富的社区插件极其丰富的插件生态
配置复杂度中等较高
学习曲线平缓陡峭
性能快速中等

与 Prettier 对比

特性StylelintPrettier
定位代码质量检查代码格式化
检查范围语法、最佳实践、规范格式、缩进、引号
可配置性高度可配置少量配置项
自动修复支持部分规则全部自动格式化
规则冲突可能与其他工具冲突统一格式，避免冲突
使用方式独立运行独立运行
集成难度需要配置开箱即用

与 PostCSS 对比

特性StylelintPostCSS
定位代码检查工具CSS 转换工具
主要功能代码质量检查CSS 转换、优化
插件类型检查规则转换插件
执行时机开发时检查构建时转换
依赖关系依赖 PostCSS 解析独立运行
使用场景代码规范功能增强

与 Stylelint 替代品对比

工具优势劣势
Stylelint规则丰富、生态完善、社区活跃配置相对复杂
Prettier开箱即用、统一格式只关注格式，不检查质量
PostCSS + 插件灵活、可扩展需要自己组合工具
CSS Modules解决样式冲突不是检查工具
Tailwind CSS原子化 CSS不是检查工具

推荐使用组合

// 最佳实践组合
{
  "开发工具": {
    "代码质量": "Stylelint + ESLint",
    "代码格式": "Prettier",
    "样式处理": "PostCSS",
    "Git 集成": "Husky + lint-staged"
  },
  "典型配置": {
    "样式检查": "stylelint-config-standard + stylelint-scss",
    "代码检查": "eslint-config-standard",
    "代码格式": "prettier + eslint-config-prettier",
    "提交检查": "husky + lint-staged"
  }
}

最佳实践

配置管理

分层配置策略

// 基础配置 stylelint.config.base.js
module.exports = {
  rules: {
    // 基础规则，所有项目共享
    'color-no-invalid-hex': true,
    'font-family-no-duplicate-names': true,
    'declaration-block-no-duplicate-properties': true,
    'block-no-empty': true
  }
}
 
// 项目配置 stylelint.config.js
module.exports = {
  extends: ['./stylelint.config.base.js'],
  rules: {
    // 项目特定规则
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$',
    'max-nesting-depth': 3
  }
}

Monorepo 配置

// packages/shared-config/stylelint.config.js
module.exports = {
  extends: ['stylelint-config-standard'],
  rules: {
    // 共享规则
  }
}
 
// apps/web/stylelint.config.js
module.exports = {
  extends: ['../../packages/shared-config/stylelint.config.js'],
  rules: {
    // Web 应用特定规则
  }
}
 
// apps/mobile/stylelint.config.js
module.exports = {
  extends: ['../../packages/shared-config/stylelint.config.js'],
  rules: {
    // Mobile 应用特定规则
  }
}

规则配置

渐进式引入规则

// 第一阶段：只检查严重问题
{
  "extends": "stylelint-config-recommended",
  "rules": {
    "color-no-invalid-hex": true,
    "property-no-unknown": true,
    "declaration-block-no-duplicate-properties": true
  }
}
 
// 第二阶段：增加规范检查
{
  "extends": "stylelint-config-standard",
  "rules": {
    "color-hex-case": "lower",
    "color-hex-length": "short",
    "indentation": 2
  }
}
 
// 第三阶段：完整规则集
{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-recommended-scss"
  ],
  "plugins": ["stylelint-order"],
  "rules": {
    // 完整规则集
  }
}

规则优先级

{
  "rules": {
    // 高优先级：避免错误
    "color-no-invalid-hex": true,
    "property-no-unknown": true,
    "selector-pseudo-class-no-unknown": true,
    
    // 中优先级：代码质量
    "declaration-block-no-duplicate-properties": true,
    "no-descending-specificity": true,
    "no-duplicate-selectors": true,
    
    // 低优先级：代码风格
    "color-hex-case": "lower",
    "indentation": 2,
    "max-empty-lines": 1
  }
}

工作流集成

开发阶段

// package.json
{
  "scripts": {
    "dev": "vite",
    "lint:css": "stylelint \"src/**/*.{css,scss,less}\"",
    "lint:css:fix": "stylelint \"src/**/*.{css,scss,less}\" --fix",
    "build": "pnpm lint:css && vite build"
  }
}

提交阶段

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
 
# 只检查暂存的文件
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=d | grep -E '\.(css|scss|less)$')
 
if [ -n "$CHANGED_FILES" ]; then
  pnpm exec stylelint $CHANGED_FILES --fix
fi
 
pnpm exec lint-staged

CI 阶段

# .github/workflows/ci.yml
name: CI
 
on: [push, pull_request]
 
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint:css
      
      - name: Upload Stylelint report
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: stylelint-report
          path: stylelint-report.json

团队协作

配置锁定

// package.json
{
  "dependencies": {
    "stylelint": "16.25.0",
    "stylelint-config-standard": "36.0.0",
    "stylelint-scss": "6.0.0"
  },
  "resolutions": {
    "stylelint": "16.25.0"
  }
}

文档化配置

<!-- STYLELINT_RULES.md -->
# Stylelint 规则说明
 
## 启用的规则
 
### 颜色规则
- `color-no-invalid-hex`: 禁止使用无效的十六进制颜色
- `color-hex-case`: 十六进制颜色使用小写
- `color-hex-length`: 使用短十六进制颜色
 
### 选择器规则
- `selector-class-pattern`: 类名使用驼峰命名
- `max-nesting-depth`: 最大嵌套深度为 3
- `no-descending-specificity`: 禁止降低特异性
 
## 自定义规则
- 类名格式：`^[a-z][a-zA-Z0-9]+$`
- 自定义属性：`^my-[a-z][a-zA-Z0-9-]+$`

技术局限与边界

已知限制

1. 性能边界

// 大型项目可能需要优化
module.exports = {
  // 排除不需要检查的文件
  ignoreFiles: [
    'node_modules/**',
    'dist/**',
    'build/**',
    '**/*.min.css',
    '**/vendor/**'
  ],
  
  // 启用缓存
  cache: true,
  
  // 限制并发数
  // 通过 --concurrency 参数控制
}

2. 规则冲突

// 与 Prettier 冲突时的解决方案
{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-prettier"  // 放在最后，覆盖冲突规则
  ]
}

3. 预处理器限制

// SCSS 嵌套可能导致问题
{
  "rules": {
    // 限制嵌套深度
    "max-nesting-depth": 3,
    
    // 忽略 SCSS 特有的 at-rule
    "scss/at-rule-no-unknown": true,
    
    // 处理 SCSS 插值
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["/^:/"]
      }
    ]
  }
}

不适用的场景

1. 运行时样式检查

Stylelint 只能检查静态样式文件，无法检查运行时动态生成的样式：

// 这种情况 Stylelint 无法检查
const dynamicStyle = {
  color: getDynamicColor()  // 运行时计算
}

2. CSS-in-JS 深度检查

虽然可以检查 CSS-in-JS，但能力有限：

// 这种复杂的 CSS-in-JS 检查效果有限
const StyledComponent = styled.div`
  color: ${props => props.theme.color};
  ${props => props.customStyles}
`

3. 样式功能验证

Stylelint 只检查语法和规范，不验证样式的实际效果：

/* 这个样式虽然通过了 Stylelint 检查，但可能有逻辑问题 */
.button {
  color: blue;
  background: blue;  /* 前景色和背景色相同，文字不可见 */
}

迁移考虑

从旧版本迁移

# 检查当前版本
stylelint --version
 
# 升级到最新版本
pnpm add -D stylelint@latest
 
# 使用迁移指南
# https://stylelint.io/migration-guide/to-16/

配置迁移

// 旧配置（已弃用）
{
  "rules": {
    "indentation": "tab",
    "max-empty-lines": 1
  }
}
 
// 新配置（v16+）
{
  "rules": {
    "indentation": "tab",
    "max-empty-lines": 1
  }
}

性能优化建议

// 大型项目推荐配置
module.exports = {
  // 启用缓存
  cache: true,
  cacheLocation: './node_modules/.cache/stylelint',
  
  // 排除大文件
  ignoreFiles: [
    'node_modules/**',
    'dist/**',
    '**/*.min.css',
    '**/vendor/**',
    '**/*.generated.css'
  ],
  
  // 使用高效的自定义语法
  customSyntax: 'postcss-scss',
  
  // 只检查必要的文件
  // 通过 CLI 参数精确控制
}

学习资源

官方资源

教程与指南

视频资源

  • YouTube 教程: 搜索 "Stylelint tutorial"
  • Bilibili: 搜索 "Stylelint 教程"
  • 前端早读课: Stylelint 相关专题

书籍推荐

  • 《前端工程化：体系设计与实践》- 包含 Stylelint 等工具的详细介绍
  • 《CSS 揭秘》- 理解 CSS 最佳实践
  • 《高性能 CSS》- 性能优化相关

社区资源

实战项目

工具集成

2026 年现状

最新版本动态

截至 2026 年初，Stylelint 的最新版本是 16.25.0（2025 年 10 月发布），v17 正在开发中。主要进展包括：

  • 批量抑制功能：实验性支持批量抑制规则警告，提升开发体验
  • CSS Baseline 支持：与 Web Platform 的 Baseline 计划对齐，支持最新的 CSS 特性
  • 不可变发布：首次实现不可变发布，确保版本稳定性
  • 性能优化：持续改进检查性能，特别是大型项目

生态发展

插件生态持续繁荣

# 2025-2026 年活跃的插件
stylelint-scss          # SCSS 支持（持续更新）
stylelint-order         # 属性排序（2026 年 3 月更新）
stylelint-plugin-defensive-css  # 防御性 CSS
stylelint-a11y          # 可访问性检查

预处理器支持成熟

  • SCSS: 通过 postcss-scss 和 stylelint-scss 提供完整支持
  • Less: 通过 postcss-less 提供良好支持
  • SugarSS: 缩进语法支持

构建工具集成完善

  • Vite: vite-plugin-stylelint 已成为标准配置
  • Webpack: stylelint-webpack-plugin 稳定成熟
  • Turborepo: 原生支持，适合 Monorepo 项目

技术趋势

1. AI 辅助检查

虽然 Stylelint 本身不直接使用 AI，但社区开始出现结合 AI 的样式检查工具，Stylelint 作为基础工具仍然不可或缺。

2. 与 Prettier 的协作

Stylelint 和 Prettier 的协作模式已经成熟，通过 stylelint-config-prettier 解决了规则冲突问题。

3. 性能持续优化

  • 缓存机制更加完善
  • 增量检查支持更好
  • 大型项目性能显著提升

4. CSS 新特性支持

随着 CSS 规范的发展，Stylelint 持续更新以支持新特性：

  • CSS Baseline 支持
  • CSS 容器查询
  • CSS 嵌套语法
  • CSS 层叠层（@layer）

社区活跃度

  • GitHub Stars: 超过 12,000+
  • npm 下载量: 每周超过 1000 万次
  • 贡献者: 500+ 活跃贡献者
  • 发布频率: 每月 1-2 个版本

与竞品对比

在 2026 年的前端工具链中，Stylelint 仍然是 CSS 检查的事实标准：

工具定位状态
StylelintCSS 代码检查活跃发展，生态完善
PrettierCSS 格式化成熟稳定，与 Stylelint 互补
ESLintJS/TS 检查活跃发展，与 Stylelint 配合使用
Tailwind CSS原子化 CSS流行趋势，但不是检查工具

未来规划

根据官方路线图，Stylelint 的未来发展方向包括：

  1. v17 发布：预计包含更多新特性和性能优化
  2. AI 集成探索：探索与 AI 工具的结合方式
  3. 性能进一步提升：针对超大项目的优化
  4. 更好的 CSS 新特性支持：持续跟进 CSS 规范发展
  5. 开发者体验改进：更友好的配置和报告

推荐配置（2026）

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-recommended-scss"
  ],
  "plugins": [
    "stylelint-scss",
    "stylelint-order"
  ],
  "customSyntax": "postcss-scss",
  "rules": {
    // 基础质量规则
    "color-no-invalid-hex": true,
    "property-no-unknown": true,
    "declaration-block-no-duplicate-properties": true,
    
    // 代码规范
    "color-hex-case": "lower",
    "color-hex-length": "short",
    "indentation": 2,
    
    // 性能优化
    "max-nesting-depth": 3,
    "selector-max-specificity": "1,2,1",
    "no-descending-specificity": true,
    
    // 现代 CSS
    "selector-not-notation": "complex",
    "media-query-no-invalid": true
  }
}

总结：Stylelint 在 2026 年仍然是前端工程化中不可或缺的 CSS 检查工具。它拥有完善的规则体系、丰富的插件生态、良好的构建工具集成，以及活跃的社区支持。无论是大型团队项目还是个人开发，Stylelint 都能帮助开发者编写更规范、更高质量的样式代码。