Skip to main content

配置

¥Configuring

Stylelint 需要一个配置对象，并在以下位置查找一个：

¥Stylelint expects a configuration object, and looks for one in a:

  • stylelint.config.js 或 .stylelintrc.js 文件

    ¥stylelint.config.js or .stylelintrc.js file

  • 使用 export default（ES 模块）的 stylelint.config.mjs 或 .stylelintrc.mjs 文件

    ¥stylelint.config.mjs or .stylelintrc.mjs file using export default (ES module)

  • 使用 module.exports (CommonJS) 的 stylelint.config.cjs 或 .stylelintrc.cjs 文件

    ¥stylelint.config.cjs or .stylelintrc.cjs file using module.exports (CommonJS)

  • .stylelintrc.json、.stylelintrc.yml 或 .stylelintrc.yaml 文件

    ¥.stylelintrc.json, .stylelintrc.yml, or .stylelintrc.yaml file

  • JSON 或 YAML 格式的 .stylelintrc 文件

    ¥.stylelintrc file in JSON or YAML format

    • 我们建议添加扩展（例如 .json）来帮助你的编辑器提供语法检查和高亮。

      ¥We recommend adding an extension (e.g., .json) to help your editor provide syntax checking and highlighting.

  • package.json 的 stylelint 处属性

    ¥stylelint property in package.json

ES 模块示例：

¥ES module example:

export default {
  rules: {
    "block-no-empty": true
  }
};

CommonJS 示例：

¥CommonJS example:

module.exports = {
  rules: {
    "block-no-empty": true
  }
};

JSON 示例：

¥JSON example:

{
  "rules": {
    "block-no-empty": true
  }
}

从当前工作目录开始，Stylelint 在找到其中之一时停止搜索。或者，你可以使用 --config 或 configFile 选项来缩短搜索。

¥Starting from the current working directory, Stylelint stops searching when one of these is found. Alternatively, you can use the --config or configFile option to short-circuit the search.

配置对象具有以下属性：

¥The configuration object has the following properties:

rules​

规则决定了 linter 查找和诉说的内容。Stylelint 中内置了 超过 100 条规则。默认情况下不启用任何规则。

¥Rules determine what the linter looks for and complains about. There are over 100 rules built into Stylelint. No rules are turned on by default.

rules 属性是一个对象，其键是规则名称，值是规则配置。例如：

¥The rules property is an object whose keys are rule names and values are rule configurations. For example:

{
  "rules": {
    "color-no-invalid-hex": true
  }
}

每个规则配置都符合以下格式之一：

¥Each rule configuration fits one of the following formats:

  • null（关闭规则）

    ¥null (to turn the rule off)

  • 单个值（主要选项）

    ¥a single value (the primary option)

  • 具有两个值的数组 ([primary option, secondary options])

    ¥an array with two values ([primary option, secondary options])

指定主要选项会启用规则。

¥Specifying a primary option turns on a rule.

许多规则提供了用于进一步定制的辅助选项。要设置辅助选项，请使用双成员数组。例如：

¥Many rules provide secondary options for further customization. To set secondary options, use a two-member array. For example:

{
  "rules": {
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["global"]
      }
    ]
  }
}

你可以向对象添加任意数量的键。例如，你可以：

¥You can add any number of keys to the object. For example, you can:

  • 关闭 block-no-empty

    ¥turn off block-no-empty

  • 使用主要选项打开 unit-allowed-list

    ¥turn on unit-allowed-list with a primary option

  • 使用主要和次要选项打开 alpha-value-notation

    ¥turn on alpha-value-notation with a primary and secondary option

{
  "rules": {
    "block-no-empty": null,
    "unit-allowed-list": ["em", "rem", "%", "s"],
    "alpha-value-notation": ["percentage", { "exceptProperties": ["opacity"] }]
  }
}

某些规则和选项接受正则表达式。你可以强制执行以下常见情况：

¥Some rules and options accept regex. You can enforce these common cases:

  • 烤肉串案例：^([a-z][a-z0-9]*)(-[a-z0-9]+)*$

    ¥kebab-case: ^([a-z][a-z0-9]*)(-[a-z0-9]+)*$

  • 小驼峰命名法：^[a-z][a-zA-Z0-9]+$

    ¥lowerCamelCase: ^[a-z][a-zA-Z0-9]+$

  • 蛇案例：^([a-z][a-z0-9]*)(_[a-z0-9]+)*$

    ¥snake_case: ^([a-z][a-z0-9]*)(_[a-z0-9]+)*$

  • 大写驼峰式：^[A-Z][a-zA-Z0-9]+$

    ¥UpperCamelCase: ^[A-Z][a-zA-Z0-9]+$

或者使用正向后向正则表达式强制执行前缀。例如，(?<=foo-) 以 foo- 为前缀。

¥Or enforce a prefix using a positive lookbehind regex. For example, (?<=foo-) to prefix with foo-.

disableFix​

你可以设置 disableFix 辅助选项以基于每个规则禁用自动修复。

¥You can set the disableFix secondary option to disable autofix on a per-rule basis.

例如：

¥For example:

{
  "rules": {
    "color-function-notation": ["modern", { "disableFix": true }]
  }
}

message​

你可以使用 message 辅助选项在违反规则时发送自定义消息。

¥You can use the message secondary option to deliver a custom message when a rule is violated.

例如，以下规则配置将替换自定义消息：

¥For example, the following rule configuration would substitute in custom messages:

{
  "rules": {
    "custom-property-pattern": [
      "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
      {
        "message": "Expected custom property name to be kebab-case"
      }
    ]
  }
}

或者，如果你需要严格的定制，你可以编写 自定义格式化程序 以获得最大程度的控制。

¥Alternately, you can write a custom formatter for maximum control if you need serious customization.

实验特点：一些规则支持消息参数。例如，配置 color-no-hex 规则时，可以在消息字符串中使用十六进制颜色：

¥Experimental feature: some rules support message arguments. For example, when configuring the color-no-hex rule, the hex color can be used in the message string:

.stylelintrc.js：

{
  'color-no-hex': [true, {
    message: (hex) => `Don't use hex colors like "${hex}"`,
  }]
}

.stylelintrc.json：

{
  "color-no-hex": [true, {
    "message": "Don't use hex colors like \"%s\""
  }]
}

对于不支持 JSON 等函数的格式，你可以使用类似 printf 的格式（例如 %s）。另一方面，对于 JS 格式，你可以同时使用类似 printf 的格式和函数。

¥With formats that don't support a function like JSON, you can use a printf-like format (e.g., %s). On the other hand, with JS format, you can use both a printf-like format and a function.

reportDisables​

你可以设置 reportDisables 辅助选项来报告此规则的任何 stylelint-disable 注释，从而有效地禁止作者选择退出。

¥You can set the reportDisables secondary option to report any stylelint-disable comments for this rule, effectively disallowing authors to opt-out of it.

例如：

¥For example:

{
  "rules": {
    "color-no-invalid-hex": [true, { "reportDisables": true }]
  }
}

该报告被认为是 lint 错误。

¥The report is considered to be a lint error.

severity​

你可以使用 severity 辅助选项来调整任何特定规则的严重性。

¥You can use the severity secondary option to adjust any specific rule's severity.

severity 的可用值为：

¥The available values for severity are:

  • "warning"

  • "error"（默认）

    ¥"error" (default)

例如：

¥For example:

{
  "rules": {
    "number-max-precision": [
      2,
      {
        "ignoreUnits": ["em"],
        "severity": "warning"
      }
    ]
  }
}

报告器可以使用这些严重级别来显示问题或以不同的方式退出流程。

¥Reporters may use these severity levels to display problems or exit the process differently.

实验特点：一些规则支持 消息参数。对于这些规则，可以使用 severity 的函数，该函数将接受这些参数，从而允许你根据这些参数调整严重性。

¥Experimental feature: some rules support message arguments. For these rules, it is possible to use a function for severity, which would accept these arguments, allowing you to adjust the severity based on these arguments.

该函数必须返回 "error"、"warning" 或 null。当它返回 null 时，将使用 defaultSeverity。

¥This function must return "error", "warning", or null. When it would return null, the defaultSeverity would be used.

例如，给定：

¥For example, given:

{
	rules: {
		'selector-disallowed-list': [
			['a > .foo', '/\\[data-.+]/'],
			{
				severity: (selector) => {
					return selector.includes('a > .foo') ? 'error' : 'warning';
				},
			},
		],
	},
}

以下模式被报告为错误：

¥The following pattern is reported as an error:

a > .foo {}

但以下模式将被报告为警告：

¥But the following pattern would be reported as a warning:

a[data-auto="1"] {}

extends​

你可以扩展现有配置（无论是你自己的还是第三方的）。配置可以打包插件、自定义语法、选项和配置规则。他们还可以扩展其他配置。

¥You can extend an existing configuration (whether your own or a third-party one). Configurations can bundle plugins, custom syntaxes, options, and configure rules. They can also extend other configurations.

例如，stylelint-config-standard 是我们可以扩展的官方配置之一。

¥For example, stylelint-config-standard is one of our official configs that you can extend.

当一个配置扩展另一个配置时，它会从另一个配置的属性开始，然后添加并覆盖其中的属性。

¥When one configuration extends another, it starts with the other's properties and then adds to and overrides what's there.

例如，要扩展 stylelint-config-standard，然后将 alpha 值更改为数字并关闭 selector-class-pattern 规则：

¥For example, to extend the stylelint-config-standard and then change the alpha values to numbers and turn off the selector-class-pattern rule:

{
  "extends": "stylelint-config-standard",
  "rules": {
    "alpha-value-notation": "number",
    "selector-class-pattern": null
  }
}

你可以扩展现有配置的数组，数组中的每个项目都优先于前一个项目（因此第二个项目覆盖第一个项目中的规则，第三个项目覆盖第一个和第二个项目中的规则，依此类推，最后一个项目 项目覆盖其他所有内容）。

¥You can extend an array of existing configurations, with each item in the array taking precedence over the previous item (so the second item overrides rules in the first, the third item overrides rules in the first and the second, and so on, the last item overrides everything else).

例如，使用 stylelint-config-standard，然后将 myExtendableConfig 放在其上，然后覆盖 alpha-value-notation 规则：

¥For example, with stylelint-config-standard, then layer myExtendableConfig on top of that, and then override the alpha-value-notation rule:

{
  "extends": ["stylelint-config-standard", "./myExtendableConfig"],
  "rules": {
    "alpha-value-notation": "number"
  }
}

"extends" 的值是 "locater"（或 "locaters" 的数组），最终是 require()d。它可以适应任何适用于 Node 的 require.resolve() 算法的格式。这意味着 "locater" 可以是：

¥The value of "extends" is a "locater" (or an array of "locaters") that is ultimately require()d. It can fit whatever format works with Node's require.resolve() algorithm. That means a "locater" can be:

  • node_modules 中模块的名称（例如 stylelint-config-standard；该模块的 main 文件必须是有效的 JSON 配置）

    ¥the name of a module in node_modules (e.g. stylelint-config-standard; that module's main file must be a valid JSON configuration)

  • 具有 .js 或 .json 扩展名的文件的绝对路径（如果你在 Node.js 上下文中创建 JS 对象并将其传入），则这是有意义的。

    ¥an absolute path to a file (which makes sense if you're creating a JS object in a Node.js context and passing it in) with a .js or .json extension.

  • 具有 .js 或 .json 扩展名的文件相对于引用配置的相对路径（例如，如果 configA 有 extends: "../configB"，我们将查找相对于 configA 的 configB）。

    ¥a relative path to a file with a .js or .json extension, relative to the referencing configuration (e.g. if configA has extends: "../configB", we'll look for configB relative to configA).

你将在 很棒的 Stylelint 中找到更多配置。

¥You'll find more configs in Awesome Stylelint.

plugins​

插件是为支持方法、工具集、非标准 CSS 功能或非常具体的用例而构建的自定义规则或自定义规则集。

¥Plugins are custom rules or sets of custom rules built to support methodologies, toolsets, non-standard CSS features, or very specific use cases.

例如，stylelint-order 是一个流行的插件包，用于对声明块中的属性等内容进行排序。

¥For example, stylelint-order is a popular plugin pack to order things like properties within declaration blocks.

插件通常包含在共享配置 你可以扩展 中。例如，stylelint-config-standard-scss 配置包含 stylelint-scss 插件。

¥Plugins are often included within shared configs that you can extend. For example, the stylelint-config-standard-scss config includes the stylelint-scss plugin.

要直接使用插件，请将 "plugins" 数组添加到你的配置中，其中包含 插件对象 或 "locaters" 来标识你要使用的插件。与上面的 extends 一样，"locater" 可以是：

¥To use a plugin directly, add a "plugins" array to your config, containing either plugin objects or "locaters" identifying the plugins you want to use. As with extends, above, a "locater" can be either a:

  • npm 模块名称

    ¥npm module name

  • 绝对路径

    ¥absolute path

  • 相对于调用配置文件的路径

    ¥path relative to the invoking configuration file

声明插件后，你需要在 "rules" 对象中添加插件规则的选项，就像任何标准规则一样。查看插件的文档以了解规则名称应该是什么。

¥Once the plugin is declared, within your "rules" object you'll need to add options for the plugin's rule(s), just like any standard rule. Look at the plugin's documentation to know what the rule name should be.

{
  "plugins": ["../special-rule.js"],
  "rules": {
    "plugin-namespace/special-rule": "everything"
  }
}

"plugin" 可以提供单个规则或一组规则。如果你使用的插件提供了一个集合，请在 "plugins" 配置值中调用该模块，并使用它在 "rules" 中提供的规则。例如：

¥A "plugin" can provide a single rule or a set of rules. If the plugin you use provides a set, invoke the module in your "plugins" configuration value, and use the rules it provides in "rules". For example:

{
  "plugins": ["../some-rule-set.js"],
  "rules": {
    "some-rule-set/first-rule": "everything",
    "some-rule-set/second-rule": "nothing",
    "some-rule-set/third-rule": "everything"
  }
}

你会在 很棒的 Stylelint 中找到更多插件。

¥You'll find more plugins in Awesome Stylelint.

customSyntax​

指定要在代码上使用的自定义语法。更多信息。

¥Specify a custom syntax to use on your code. More info.

overrides​

使用 overrides 属性，你可以指定要应用配置的文件子集。

¥Using the overrides property, you can specify what subset of files to apply a configuration to.

例如，要使用：

¥For example, to use the:

  • 所有 .scss 文件的 postcss-scss 语法

    ¥postcss-scss syntax for all .scss files

  • components 和 pages 目录中所有 .css 文件中所有 alpha 值的 percentage 表示法

    ¥percentage notation for all alpha values in all .css files in the components and pages directories

{
  "rules": {
    "alpha-value-notation": "number"
  },
  "overrides": [
    {
      "files": ["*.scss", "**/*.scss"],
      "customSyntax": "postcss-scss"
    },
    {
      "files": ["components/**/*.css", "pages/**/*.css"],
      "rules": {
        "alpha-value-notation": "percentage"
      }
    }
  ]
}

overrides 属性的值是一个对象数组。每个对象：

¥The value of the overrides property is an array of objects. Each object:

  • 必须包含 files 属性，它是一个 glob 模式数组，指定配置应应用于哪些文件

    ¥must contain a files property, which is an array of glob patterns that specify which files the configuration should be applied to

  • 应至少包含一个其他常规配置属性，例如 customSyntax、rules、extends 等。

    ¥should contain at least one other regular configuration property, such as customSyntax, rules, extends, etc.

customSyntax 属性将被替换，而 plugins、extends、rules 等将被附加。

¥The customSyntax property will be replaced, whereas plugins, extends, rules, etc. will be appended.

模式应用于相对于配置文件目录的文件路径。例如，如果你的配置文件具有路径 /project-foo/.stylelintrc.js，而你想要 lint 的文件具有路径 /project-foo/components/bar.css，则 .stylelintrc.js 中提供的模式将针对相对路径 components/bar.css 执行。

¥Patterns are applied against the file path relative to the directory of the config file. For example, if your config file has the path /project-foo/.stylelintrc.js and the file you want to lint has the path /project-foo/components/bar.css, then the pattern provided in .stylelintrc.js will be executed against the relative path components/bar.css.

覆盖的优先级高于常规配置。同一配置中的多个覆盖按顺序应用。也就是说，配置文件中的最后一个覆盖块始终具有最高优先级。

¥Overrides have higher precedence than regular configurations. Multiple overrides within the same config are applied in order. That is, the last override block in a config file always has the highest precedence.

defaultSeverity​

你可以为所有未在其辅助选项中指定严重性的规则设置默认严重性级别。例如，你可以将默认严重性设置为 "warning"：

¥You can set the default severity level for all rules that do not have a severity specified in their secondary options. For example, you can set the default severity to "warning":

{
  "defaultSeverity": "warning"
}

report*​

这些 report* 属性为 stylelint-disable 注释提供额外的验证。这可以帮助强制实现有用且有据可查的禁用。

¥These report* properties provide extra validation for stylelint-disable comments. This can help enforce useful and well-documented disables.

可用的报告有：

¥The available reports are:

它们的配置就像规则一样。它们可以具有以下三个值之一：

¥They are configured like rules. They can have one of three values:

  • null（关闭配置）

    ¥null (to turn the configuration off)

  • true 或 false（主要选项）

    ¥true or false (the primary option)

  • 具有两个值的数组 ([primary option, secondary options])

    ¥an array with two values ([primary option, secondary options])

可以使用以下辅助选项：

¥The following secondary options are available:

  • "except" 采用规则名称数组，应反转其主要选项。

    ¥"except" takes an array of rule names for which the primary option should be inverted.

  • "severity" 调整规则 如上 触发的错误级别。

    ¥"severity" adjusts the level of error emitted for the rule, as above.

例如，这会因不必要地禁用除 selector-max-type 之外的所有规则而产生错误：

¥For example, this produces errors for needless disables of all rules except selector-max-type:

{
  "reportNeedlessDisables": [true, { "except": ["selector-max-type"] }]
}

这会触发关于禁用没有描述的 unit-allowed-list 的警告：

¥And this emits warnings for disables of unit-allowed-list that don't have a description:

{
  "reportDescriptionlessDisables": [
    false,
    {
      "except": ["unit-allowed-list"],
      "severity": "warning"
    }
  ]
}

reportDescriptionlessDisables​

报告 stylelint-disable 条注释，但不加说明。report* 属性。

¥Report stylelint-disable comments without a description. A report* property.

例如：

¥For example:

{
  "reportDescriptionlessDisables": true
}

更多信息。

¥More info.

reportInvalidScopeDisables​

报告与配置对象中指定的规则不匹配的 stylelint-disable 注释。report* 属性。

¥Report stylelint-disable comments that don't match rules that are specified in the configuration object. A report* property.

例如：

¥For example:

{
  "reportInvalidScopeDisables": true
}

更多信息。

¥More info.

reportNeedlessDisables​

报告 stylelint-disable 条与任何需要禁用的 lint 不匹配的注释。report* 属性。

¥Report stylelint-disable comments that don't match any lints that need to be disabled. A report* property.

例如：

¥For example:

{
  "reportNeedlessDisables": true
}

更多信息。

¥More info.

configurationComment​

你可以设置像 /* stylelint-disable */ 这样的配置注释以什么开头。如果你使用具有不同配置的 Stylelint 的多个实例，这会很有用。

¥You can set what configuration comments like /* stylelint-disable */ start with. This can be useful if you use multiple instances of Stylelint with different configurations.

例如，要让 Stylelint 实例禁用带有 /* stylelint-foo-instance-disable */ 而不是默认 /* stylelint-disable */ 的规则：

¥For example, to have an instance of Stylelint disable rules with /* stylelint-foo-instance-disable */ instead of the default /* stylelint-disable */:

{
  "configurationComment": "stylelint-foo-instance"
}

ignoreDisables​

忽略 stylelint-disable（例如 /* stylelint-disable block-no-empty */）注释。

¥Ignore stylelint-disable (e.g. /* stylelint-disable block-no-empty */) comments.

例如：

¥For example:

{
  "ignoreDisables": true
}

更多信息。

¥More info.

ignoreFiles​

你可以提供一个 glob 或 glob 数组来忽略特定文件。

¥You can provide a glob or array of globs to ignore specific files.

例如，你可以忽略所有 JavaScript 文件：

¥For example, you can ignore all JavaScript files:

{
  "ignoreFiles": ["**/*.js"]
}

Stylelint 默认忽略 node_modules 目录。但是，如果设置了 ignoreFiles，则该设置将被覆盖。

¥Stylelint ignores the node_modules directory by default. However, this is overridden if ignoreFiles is set.

如果 glob 是绝对路径，则按原样使用它们。如果它们是相对的，则相对于它们进行分析

¥If the globs are absolute paths, they are used as is. If they are relative, they are analyzed relative to

  • configBasedir，如果提供的话；

    ¥configBasedir, if it's provided;

  • 配置的文件路径，如果配置是 Stylelint 找到并加载的文件；

    ¥the config's filepath, if the config is a file that Stylelint found and loaded;

  • 或 process.cwd()。

    ¥or process.cwd().

NOTE

这不是忽略大量文件的有效方法。如果你想有效地忽略大量文件，请使用 .stylelintignore 或调整文件全局。

¥This is not an efficient method for ignoring lots of files. If you want to ignore a lot of files efficiently, use .stylelintignore or adjust your files globs.

allowEmptyInput​

当 glob 模式不匹配任何文件时，Stylelint 不会抛出错误。

¥Stylelint does not throw an error when the glob pattern matches no files.

例如：

¥For example:

{
  "allowEmptyInput": true
}
NOTE

不应在每个文件的基础上覆盖此配置选项。

¥This config option should not be overridden on a per-file basis.

更多信息。

¥More info.

cache​

存储处理文件的结果，以便 Stylelint 只对更改的文件进行操作。

¥Store the results of processed files so that Stylelint only operates on the changed ones.

例如：

¥For example:

{
  "cache": true
}
NOTE

不应在每个文件的基础上覆盖此配置选项。

¥This config option should not be overridden on a per-file basis.

更多信息。

¥More info.

fix​

如果可能，自动修复规则报告的问题。

¥Automatically fix, where possible, problems reported by rules.

例如：

¥For example:

{
  "fix": true
}
NOTE

不应在每个文件的基础上覆盖此配置选项。

¥This config option should not be overridden on a per-file basis.

更多信息。

¥More info.