Stylelint

杜俊风

2023-12-01

中文翻译文档（稍晚于官方）https://cloud.tencent.com/developer/doc/1267

stylelint是什么

A mighty, modern CSS linter and fixer that helps you avoid errors and enforce consistent conventions in your stylesheets.
一款强大的，现代的css语法检查和纠错工具，它可以帮助开发者在编写样式文件时避免错误，同时它还可以强迫开发者们形成统一的开发规范。

简而言之，stylelint是个css语法检查器，它由PostCSS提供。

PostCSS就像Babel的css版，会把css转成ast（抽象语法树，可以理解为一个描述代码内容的层层嵌套的对象），然后用各种插件处理它，最后再转回css，可以靠它实现自动添加样式的浏览器前缀、使用未来的CSS4语法等。
通过解析ast，PostCSS可以支持scss,less等css预处理语言，因此，stylelint也同样支持。

本文将介绍stylelint在webpack中以plugin形式的使用，和在vscode中以扩展的形式的使用，其他情况可参考stylelint官网–辅助工具和常见问题。

配置

核心

不同场景下stylelint的使用都需要一个配置对象（configuration object）。

如同babel和eslint，它们都用cosmiconfig加载配置，所以你的配置对象可以写在：

package.json的stylelint属性中，如：

{
  "extends": "stylelint-config-standard",
  "rules":{
    "string-quotes": "single",
    // ...
  },
  // ...
}

.stylelintrc文件中；
传出对象的stylelint.config.js文件中。

它们会在stylelint被运行时自动查到并使用。

对象中包含以下可配置项（一般了解rules和extends即可）：

rules

rules是一个对象，键是规则名，值是规则配置，它决定了stylelint校验代码的规则，默认情况下，没有任何规则是开启的。查看所有rules

extends

extends是一个字符串或者字符串的数组，字符串是引入的扩展的模块名或者扩展文件的地址。
一个扩展相当于一组规则，rules中的规则会覆盖和extends中重复的规则，extends是数组时，扩展中重复的规则后者会覆盖前者。
对于不想开启的extends中的规则，我们可以在rules中将该规则的值设为null。
官方推荐的两个扩展：

stylelint-config-recommended开启了所有可能有错的样式的验证规则。
stylelint-config-standard开启了60多个风格规则并设置了实用的默认配置。

plugins

插件，用法和extends类似，可以用来去支持验证一些特殊的情况，这里不做过多介绍。查看常见plugins

processors

可以用来验证非层叠样式表文件的css样式，比如html文件中的style标签，markdown文件中的代码块，JavaScript中的字符串。查看常见processors

ignoreFiles

可以用来忽略特定文件，但如果想有效地忽略大量文件，应使用.stylelintignore文件。

defaultSeverity

对所有规则验证的默认严重级别，可选"warning"（警告）和"error"（报错）,默认都是报错。

在webpack中使用

先安装stylelint-webpack-plugin：

注意：该插件要求Node至少v6.9.0，webpack至少v4.0.0。

npm install stylelint-webpack-plugin --save-dev

在webpack配置中：

// webpack.config.js
const StyleLintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  // ...
  plugins: [
    new StyleLintPlugin(options),
  ],
  // ...
}

stylelint-webpack-plugin会将这里的options直接传给stylelint.lint方法，下面只列几个较实用的设置项，其他可参考The stylelint Node API。

fix：为true时，stylelint会自动修复能修复的错误，不能修复才报错。
syntax：指定语法规则，可选scss/less/sugarss，不指定时默认读文件后缀识别。
cache：缓存上次检查结果，再次运行只检查脏值，可以提高检查效率。

stylelint.lint调用时默认会读取.stylelintrc文件或者package.json中stylelint的配置，因此不必刻意设置stylelint-webpack-plugin的options，把配置内容写在对应地方即可。

在vscode中使用

安装：在vscode中搜扩展stylelint，安装数最多的那个就是。

安装后建议关闭vscode内置的样式验证，在设置中添加:

{
  "css.validate":false,
  "less.validate":false,
  "scss.validate":false
}

强烈建议在项目中添加配置文件来使用stylelint，但扩展的设置也可以用：

stylelint.enable：ture/false，是否启用。
stylelint.configOverrides：设置stylelint的configOverrides选项，会覆盖已有配置。
stylelint.config：设置stylelint的config选项，如果设置了编辑器就不读项目的配置文件了。