Skip to main content

迁移到 14.0.0

¥Migrating to 14.0.0

此版本包含重大更改。我们知道这些可能会造成破坏,但它们需要使我们的依赖保持最新并且 Stylelint 不存在安全问题。

¥This release contains breaking changes. We know these can be disruptive, but they were needed to keep our dependencies up to date and Stylelint free of security issues.




¥There are five changes that may affect you:

  • 删除了 syntax 选项和自动推断语法

    ¥the syntax option and automatic inferral of syntax were removed

  • Node.js 10 支持已取消

    ¥Node.js 10 support was dropped

  • 13.7.0 中弃用的规则已被删除

    ¥the rules deprecated in 13.7.0 were removed

  • configOverrides 选项已删除

    ¥the configOverrides option was removed

  • function-calc-no-invalid 规则已删除

    ¥the function-calc-no-invalid rule was removed

如果你需要更新配置文件,你可能还需要删除 .stylelintcache 文件。

¥If you need to update your config file, you may need to delete your .stylelintcache file too.

syntax 选项和语法自动推断

¥syntax option and automatic inferral of syntax

Stylelint 不再包含以下语法:

¥Stylelint no longer includes the syntaxes that:

  • 解析类似 CSS 的语言,如 SCSS、Sass、Less 和 SugarSS

    ¥parse CSS-like languages like SCSS, Sass, Less and SugarSS

  • 从 HTML、Markdown 和 CSS-in-JS 对象和模板文本中提取样式

    ¥extract styles from HTML, Markdown and CSS-in-JS object & template literals

如果你使用 Stylelint 来检查 CSS 文件以外的任何内容,则需要安装和配置这些语法。我们推荐 extending 共享配置,其中包括适合你的 PostCSS 语法。例如,如果你使用 Stylelint 来检查 SCSS,则可以扩展 stylelint-config-standard-scss 共享配置

¥If you use Stylelint to lint anything other than CSS files, you will need to install and configure these syntaxes. We recommend extending a shared config that includes the appropriate PostCSS syntax for you. For example, if you use Stylelint to lint SCSS, you can extend the stylelint-config-standard-scss shared config.


¥First, install the shared config as a dependency:

npm install --save-dev stylelint-config-standard-scss

然后,更新你的 配置对象 以使用它:

¥Then, update your configuration object to use it:

"extends": ["stylelint-config-standard-scss"],
"rules": {

此共享配置扩展了 Stylelint 以与 SCSS 兼容。它为 SCSS 配置 内置规则,并包括 postcss-scss 语法stylelint-scss 插件(特定于 SCSS 的规则集合)。

¥This shared config extends Stylelint to be compatible with SCSS. It configures the built-in rules for SCSS, and includes the postcss-scss syntax and stylelint-scss plugin (a collection of rules specific to SCSS).


¥There are other shared configs provided for each language:

如果共享配置不适用于你的首选语言或库,那么你可以自行安装适当的 PostCSS 语法 并使用 customSyntax 选项,该配置现在在配置对象中可用。

¥If a shared config isn't available for your preferred language or library, then you can install the appropriate PostCSS syntax yourself and use the customSyntax option, which is now available in the configuration object.

例如,检查 SugarSS

¥For example, to lint SugarSS.

首先,安装 无糖语法 作为依赖:

¥First, install the sugarss syntax as a dependency:

npm install --save-dev sugarss


¥Then, update your configuration object to use it:

"customSyntax": "sugarss",
"rules": {

对于其他语言和嵌入样式,我们建议使用以下 PostCSS 语法

¥For other languages and embedded styles, we suggest the following PostCSS syntaxes:

@stylelint/postcss-css-in-js有问题。将来可能会被弃用,取而代之的是仅专注于一个库的较小语法(请参阅 这个问题))。

¥(The @stylelint/postcss-css-in-js package has issues. It will likely to be deprecated in the future in favor of smaller syntaxes that focus on only one library (see this issue)).

如果你 lint 不止一种样式语言,那么你可以使用新的 overrides 属性。例如,要检查 CSS 和 SugarSS,你可以更新配置对象以包括:

¥If you lint more than one styling language, then you can use the new overrides property. For example, to lint both CSS and SugarSS you can update your configuration object to include:

"extends": ["stylelint-config-standard"],
"overrides": [
"files": ["**/*.sss"],
"customSyntax": "sugarss",
"rules": {
"block-closing-brace-empty-line-before": null,
"block-closing-brace-newline-after": null,
"block-closing-brace-newline-before": null,
"block-closing-brace-space-before": null,
"block-opening-brace-newline-after": null,
"block-opening-brace-space-after": null,
"block-opening-brace-space-before": null,
"declaration-block-semicolon-newline-after": null,
"declaration-block-semicolon-space-after": null,
"declaration-block-semicolon-space-before": null,
"declaration-block-trailing-semicolon": null

这将扩展 官方标准配置,然后使用 overrides 属性设置 customSyntax 属性并关闭检查 SugarSS 文件的大括号和分号的规则。

¥Which will extend the official standard config, then use the overrides property to set the customSyntax property and turn off the rules that check braces and semicolons for SugarSS files.

然后,你可以使用 Stylelint 来检查 CSS 和 SugarSS 文件:

¥You can then use Stylelint to lint both CSS and SugarSS files:

npx stylelint "**/*.{css,sss}"

Node.js 10

对 Node.js 10 的支持已取消。你应该使用以下或更高版本的 Node.js:

¥Support for Node.js 10 was dropped. You should use the following or higher versions of Node.js:

  • 12.20.0

  • 14.13.1

  • 16.0.0

13.7.0 中已弃用的规则

¥Rules deprecated in 13.7.0

13.7.0 中弃用的规则已被删除。你应该参考 13.7.0 CHANGELOG 条目中的替代方案列表 并使用它们。

¥The rules deprecated in 13.7.0 were removed. You should refer to the list of alternatives in the 13.7.0 CHANGELOG entry and use them instead.

configOverrides 选项

¥configOverrides option

configOverrides 选项已被删除。请改用配置对象中的 overrides 属性

¥The configOverrides option has been removed. Use the overrides property in the configuration object instead.

function-calc-no-invalid 规则

¥function-calc-no-invalid rule

function-calc-no-invalid 已被删除。你应该将其从配置对象中删除。

¥The function-calc-no-invalid has been removed. You should remove it from your configuration object.


¥Plugin authors


¥There are three changes that may affect you:

  • PostCSS 版本 8 现在用于 stylelint

    ¥version 8 of PostCSS is now used in stylelint

  • 添加了 disableFix 次要选项

    ¥a disableFix secondary option was added

  • TypeScript 类型定义已添加到包中

    ¥TypeScript type definitions were added to the package

PostCSS 8

PostCSS 版本 8 中解析器的行为发生了变化。以下内容之前被解析为 Rule,现在被解析为 Declaration

¥The behavior of the parser has changed in PostCSS version 8. The following is now parsed as a Declaration when it was previously parsed as a Rule:

foo: {
bar: baz;


¥If your plugin targets this construct, you'll need to update your logic.

即使 stylelint 中使用了 PostCSS 的第 8 版,你也不能使用 新的访客 API,因为 Stylelint 插件会被 Stylelint 本身转换为使用 Once。你应该继续使用 walk* API。

¥Even though version 8 of PostCSS is used in stylelint, you can't use the new Visitor API as Stylelint plugins are converted to use Once by Stylelint itself. You should continue to use the walk* API.

disableFix 次要选项

¥disableFix secondary option

我们之前建议插件作者提供此选项。它现在在 Stylelint 本身中可用,你应该从插件中删除该选项。

¥We previously suggested plugin authors provide this option. It is now available in Stylelint itself, and you should remove the option from your plugin.

内置 TypeScript 定义

¥Built-in TypeScript definitions

stylelint 包现在导出自己的 TypeScript 类型定义。如果你使用的是 @types/stylelint 包,则应该将其从依赖中删除。

¥The stylelint package exports its own TypeScript type definitions now. If you are using the @types/stylelint package, you should remove it from your dependencies.