简介

eslint-plugin-yml 是一个为 [YAML] 提供代码检查规则的 ESLint 插件。

:name_badge: 特性

这个 ESLint 插件为 [YAML] 提供代码检查规则。

你可以使用 ESLint 来检查 [YAML]。
你可以发现 [YAML] 文件中的问题。
你可以对 [YAML] 文件应用一致的代码风格。
支持 Vue SFC 自定义块，如 <i18n lang="yaml">。要求 vue-eslint-parser v7.3.0 及以上版本。
支持 ESLint 指令。例如 # eslint-disable-next-line
你可以使用 ESLint 编辑器集成实时检查你的代码。

你可以在在线演示中进行检查。

:question: 与其他 YAML 插件有何不同？

不使用 AST 的插件

例如 eslint-plugin-yaml

这些插件使用处理器独立解析并返回结果，而不向 ESLint 引擎提供 AST 和源代码文本。

插件不提供 AST，所以你无法使用指令注释（例如 # eslint-disable）。插件不提供源代码文本，所以你无法与使用文本的插件和规则一起使用（例如 eslint-plugin-prettier，eol-last）。

eslint-plugin-yml 通过向 ESLint 提供 AST 和源代码文本来工作。

:book: 用法

配置

新配置 (`eslint.config.js`)

使用 eslint.config.js 文件来配置规则。另见：https://eslint.org/docs/latest/use/configure/configuration-files-new。

示例 eslint.config.js：

import eslintPluginYml from 'eslint-plugin-yml';
export default [
  // 在这里添加更多通用规则集，例如：
  // js.configs.recommended,
  ...eslintPluginYml.configs['flat/recommended'],
  {
    rules: {
      // 在这里覆盖/添加规则设置，例如：
      // 'yml/rule-name': 'error'
    }
  }
];

此插件提供以下配置：

*.configs['flat/base'] ... 启用正确的 YAML 解析的配置。
*.configs['flat/recommended'] ... 上述配置，加上防止错误或意外行为的规则。
*.configs['flat/standard'] ... 上述配置，加上强制执行常见风格约定的规则。
*.configs['flat/prettier'] ... 关闭可能与 Prettier 冲突的规则。

查看规则列表以获取此插件提供的 rules。

旧配置 (`.eslintrc`)

使用 .eslintrc.* 文件来配置规则。另见：https://eslint.org/docs/latest/use/configure/。

示例 .eslintrc.js：

module.exports = {
  extends: [
    // 在这里添加更多通用规则集，例如：
    // 'eslint:recommended',
    "plugin:yml/standard",
  ],
  rules: {
    // 在这里覆盖/添加规则设置，例如：
    // 'yml/rule-name': 'error'
  },
};

此插件提供以下配置：

plugin:yml/base ... 启用正确的 YAML 解析的配置。
plugin:yml/recommended ... 上述配置，加上防止错误或意外行为的规则。
plugin:yml/standard ... 上述配置，加上强制执行常见风格约定的规则。
plugin:yml/prettier ... 关闭可能与 Prettier 冲突的规则。

查看规则列表以获取此插件提供的 rules。

解析器配置

如果你已经指定了解析器，你需要为 .yaml 配置解析器。

例如，如果你正在使用 "@babel/eslint-parser"，请按如下方式配置：

module.exports = {
  // ...
  extends: ["plugin:yml/standard"],
  // ...
  parser: "@babel/eslint-parser",
  // 添加一个 `overrides` 部分来为 YAML 添加解析器配置。
  overrides: [
    {
      files: ["*.yaml", "*.yml"],
      parser: "yaml-eslint-parser",
    },
  ],
  // ...
};

解析器选项

通过在 ESLint 配置文件中的 parserOptions 中指定，可以使用以下 yaml-eslint-parser 的解析器选项。

module.exports = {
  // ...
  overrides: [
    {
      files: ["*.yaml", "*.yml"],
      parser: "yaml-eslint-parser",
      // 与 yaml-eslint-parser 一起使用的选项。
      parserOptions: {
        defaultYAMLVersion: "1.2",
      },
    },
  ],
  // ...
};

另见 https://github.com/ota-meshi/yaml-eslint-parser#readme。

从命令行运行 ESLint

如果你想从命令行运行 eslint，请确保使用 --ext 选项包含 .yaml 扩展名或使用 glob 模式，因为 ESLint 默认只针对 .js 文件。

示例：

eslint --ext .js,.yaml,.yml src
eslint "src/**/*.{js,yaml,yml}"

:computer: 编辑器集成

Visual Studio Code

使用 Microsoft 官方提供的 dbaeumer.vscode-eslint 扩展。

你必须配置扩展的 eslint.validate 选项来检查 .yaml 文件，因为该扩展默认只针对 *.js 或 *.jsx 文件。

示例 .vscode/settings.json：

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "yaml",
    "github-actions-workflow" // 用于 GitHub Actions 工作流文件
  ]
}

JetBrains WebStorm IDEs

在任何 JetBrains IDE 中，你都可以配置代码检查范围。按照他们的帮助文档中的步骤，你可以将 YAML 文件添加到范围内，如下所示：

打开 设置/首选项 对话框，转到 语言和框架 | JavaScript | 代码质量工具 | ESLint，选择 自动 ESLint 配置 或 手动 ESLint 配置。
在 运行文件 字段中，更新定义要检查的文件集的模式，以包含 YAML 文件：

{**/*,*}.{js,ts,jsx,tsx,html,vue,yaml,yml}
^^^^ ^^^

:white_check_mark: 规则

在命令行上的 --fix 选项会自动修复下面带有扳手 :wrench: 的规则报告的问题。带有以下星号 :star: 的规则包含在配置中。

YAML 规则

规则 ID	描述	可修复	推荐	标准
yml/block-mapping-colon-indicator-newline	强制 `:` 指示符后的一致换行	:wrench:
yml/block-mapping-question-indicator-newline	强制 `?` 指示符后的一致换行	:wrench:		:star:
yml/block-mapping	要求或禁止块样式映射	:wrench:		:star:
yml/block-sequence-hyphen-indicator-newline	强制 `-` 指示符后的一致换行	:wrench:		:star:
yml/block-sequence	要求或禁止块样式序列	:wrench:		:star:
yml/file-extension	强制 YAML 文件扩展名
yml/indent	强制一致的缩进	:wrench:		:star:
yml/key-name-casing	强制键名的命名约定
yml/no-empty-document	禁止空文档		:star:	:star:
yml/no-empty-key	禁止空映射键		:star:	:star:
yml/no-empty-mapping-value	禁止空映射值		:star:	:star:
yml/no-empty-sequence-entry	禁止空序列项		:star:	:star:
yml/no-tab-indent	禁止使用制表