跳至主要内容

配置

Stylelint 期望一个配置对象，并在以下文件中查找：

  • stylelint.config.js 或 .stylelintrc.js 文件
  • stylelint.config.mjs 或 .stylelintrc.mjs 文件，使用 export default（ES 模块）
  • stylelint.config.cjs 或 .stylelintrc.cjs 文件，使用 module.exports（CommonJS）
  • .stylelintrc.json、.stylelintrc.yml 或 .stylelintrc.yaml 文件
  • .stylelintrc 文件，以 JSON 或 YAML 格式
    • 我们建议添加扩展名（例如，.json），以帮助您的编辑器提供语法检查和高亮显示。
  • package.json 中的 stylelint 属性

ES 模块示例

/** @type {import('stylelint').Config} */
export default {
  rules: {
    "block-no-empty": true
  }
};
注意

@type JSDoc 注释使 Typescript 能够自动完成和类型检查。

CommonJS 示例

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

JSON 示例

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

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

配置对象具有以下属性

rules​

规则决定了 linter 寻找什么以及抱怨什么。Stylelint 内置了 超过 100 条规则。默认情况下，没有规则被启用。

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

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

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

  • null（关闭规则）
  • 单个值（主要选项）
  • 包含两个值的数组（[主要选项，次要选项]）

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

许多规则提供次要选项以进行进一步的自定义。要设置次要选项，请使用一个包含两个成员的数组。例如

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

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

  • 关闭 block-no-empty
  • 使用主要选项启用 unit-allowed-list
  • 使用主要和次要选项启用 alpha-value-notation
{
  "rules": {
    "block-no-empty": null,
    "unit-allowed-list": ["em", "rem", "%", "s"],
    "alpha-value-notation": ["percentage", { "exceptProperties": ["opacity"] }]
  }
}

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

  • kebab-case: ^([a-z][a-z0-9]*)(-[a-z0-9]+)*$
  • lowerCamelCase: ^[a-z][a-zA-Z0-9]+$
  • snake_case: ^([a-z][a-z0-9]*)(_[a-z0-9]+)*$
  • UpperCamelCase: ^[A-Z][a-zA-Z0-9]+$

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

disableFix​

您可以设置 disableFix 次要选项来按规则禁用自动修复。

例如

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

message​

您可以使用 message 次要选项在违反规则时传递自定义消息。

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

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

或者，如果您需要进行大量自定义，可以编写一个 自定义格式化程序 以获得最大控制权。

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

.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 类似的格式和函数。

reportDisables​

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

例如

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

该报告被认为是 lint 错误。

severity​

您可以使用 severity 次要选项来调整任何特定规则的严重程度。

severity 的可用值为

  • "warning"
  • "error"（默认）

例如

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

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

实验性功能：某些规则支持 消息参数。对于这些规则，可以使用 severity 的函数，该函数将接受这些参数，允许您根据这些参数调整严重程度。

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

例如，给定

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

以下模式将被报告为错误

a > .foo {}

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

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

extends​

您可以扩展现有配置（无论是您自己的还是第三方配置）。配置可以捆绑插件、自定义语法、选项以及配置规则。它们还可以扩展其他配置。

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

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

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

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

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

例如，使用 stylelint-config-standard，然后在它之上添加 myExtendableConfig，然后覆盖 alpha-value-notation 规则

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

"extends" 的值是一个“定位器”（或“定位器”数组），最终将被 require()。它可以适应与 Node 的 require.resolve() 算法一起使用的任何格式。这意味着“定位器”可以是

  • node_modules 中的模块名称（例如，stylelint-config-standard；该模块的 main 文件必须是一个有效的 JSON 配置）
  • 文件的绝对路径（如果您在 Node.js 上下文中创建了一个 JS 对象并将其传递进来，这很有意义），扩展名为 .js 或 .json。
  • 相对于引用配置的文件的相对路径（例如，如果 configA 有 extends: "../configB"，我们将相对于 configA 查找 configB）。

您可以在 精选 Stylelint 中找到更多配置。

plugins​

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

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

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

要直接使用插件，请在您的配置中添加一个 "plugins" 数组，其中包含 插件对象 或标识您要使用的插件的“定位器”。与上面的 extends 一样，“定位器”可以是

  • npm 模块名称
  • 绝对路径
  • 相对于调用配置文件的路径

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

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

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

{
  "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 中找到更多插件。

customSyntax​

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

overrides​

使用 overrides 属性，您可以指定要将配置应用于哪些文件的子集。

例如，要使用

  • postcss-scss 语法用于所有 .scss 文件
  • percentage 表示法用于 components 和 pages 目录中所有 .css 文件中的所有 alpha 值
{
  "rules": {
    "alpha-value-notation": "number"
  },
  "overrides": [
    {
      "files": ["*.scss", "**/*.scss"],
      "customSyntax": "postcss-scss"
    },
    {
      "files": ["components/**/*.css", "pages/**/*.css"],
      "rules": {
        "alpha-value-notation": "percentage"
      }
    }
  ]
}

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

  • 必须包含一个 files 属性，该属性是一个 glob 模式数组，指定应将配置应用于哪些文件
  • 应该包含至少一个其他常规配置属性，例如 customSyntax、rules、extends 等。

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

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

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

defaultSeverity​

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

{
  "defaultSeverity": "warning"
}

report*​

这些 report* 属性为 stylelint-disable 注释提供额外的验证。这有助于强制执行有用的和记录良好的禁用。

可用的报告是

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

  • null（关闭配置）
  • true 或 false（主要选项）
  • 包含两个值的数组（[主要选项，次要选项]）

以下辅助选项可用

  • "except" 接受一个规则名称数组，对于这些规则名称，应反转主要选项。
  • "severity" 调整为规则发出的错误级别，如上所述。

例如，这会为除 selector-max-type 之外的所有规则的无用禁用生成错误

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

这会为没有描述的 unit-allowed-list 禁用发出警告

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

reportDescriptionlessDisables​

报告没有描述的 stylelint-disable 注释。一个 report* 属性。

例如

{
  "reportDescriptionlessDisables": true
}

更多信息.

reportInvalidScopeDisables​

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

例如

{
  "reportInvalidScopeDisables": true
}

更多信息.

reportNeedlessDisables​

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

例如

{
  "reportNeedlessDisables": true
}

更多信息.

configurationComment​

您可以设置类似 /* stylelint-disable */ 的配置注释的开头。如果您使用多个具有不同配置的 Stylelint 实例，这将很有用。

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

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

ignoreDisables​

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

例如

{
  "ignoreDisables": true
}

更多信息.

ignoreFiles​

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

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

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

Stylelint 默认情况下会忽略 node_modules 目录。但是，如果设置了 ignoreFiles，则会覆盖此设置。

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

  • configBasedir（如果提供）；
  • 配置的文件路径（如果配置是 Stylelint 找到并加载的文件）；
  • 或 process.cwd()。
注意

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

allowEmptyInput​

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

例如

{
  "allowEmptyInput": true
}
注意

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

更多信息.

cache​

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

例如

{
  "cache": true
}
注意

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

更多信息.

fix​

尽可能自动修复规则报告的问题。

例如

{
  "fix": true
}
注意

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

更多信息.