yaml¶

此规则使用 yamllint 库检查 YAML 语法，但使用特定的默认配置，该配置与我们的内部格式化工具 (--fix) 和 prettier 兼容。

可以通过在 Ansible-lint 配置中的 skip_list 中添加 yaml 来禁用 YAML 语法违规，如下所示

skip_list:
  - yaml

要进行更细粒度的控制，请使用 yaml[yamllint_rule] 格式中的标签标识符禁用特定规则的违规，如下所示

skip_list:
  - yaml[trailing-spaces]
  - yaml[indentation]

如果希望 Ansible-lint 将 YAML 语法违规报告为警告，而不是致命错误，请在配置中的 warn_list 中添加标签标识符，例如

warn_list:
  - yaml[document-start]

警告

您不能使用 tags: [skip_ansible_lint] 来禁用此规则，但是可以使用 yamllint 魔术注释进行调整。

有关更多信息，请参阅 yamllint 规则列表。

您可能会看到的一些详细错误代码是

yaml[brackets] - 空括号内的空格太少，或括号内的空格太多
yaml[colons] - 冒号前的空格太多，或冒号后的空格太多
yaml[commas] - 逗号前的空格太多，或逗号后的空格太少
yaml[comments-indentation] - 注释的缩进与内容不同
yaml[comments] - 注释前的空格太少，或注释中缺少起始空格
yaml[document-start] - 缺少文档开头 "---" 或 发现禁止的文档开头 "---"
yaml[empty-lines] - 空白行太多 (...> ...)
yaml[indentation] - 错误的缩进：预期 ... 但发现 ...
yaml[key-duplicates] - 映射中键 "..." 重复
yaml[line-length] - 行太长（... > ... 个字符）
yaml[new-line-at-end-of-file] - 文件末尾没有换行符
yaml[octal-values]: 禁止隐式或显式八进制值
yaml[syntax] - YAML 语法已损坏
yaml[trailing-spaces] - 在行尾找到空格
yaml[truthy] - 真值应该是 ... 之一

八进制¶

由于 YAML 规范关于八进制值的规定在 1.1、1.2.0 和 1.2.2 中至少更改了 3 次，我们现在要求用户始终在八进制值周围添加引号，以便所有 YAML 加载器都将其作为字符串加载，从而提供一致的行为。这也更安全，因为 JSON 也不支持八进制值。

默认情况下，yamllint 不会检查八进制值，但我们的自定义默认规则集会检查这些。如果由于某些原因您不想遵循我们的默认设置，则可以在项目中创建一个 .yamllint 文件，这将优先于我们的默认设置。

多行字符串的附加信息¶

为了遵守 yaml[line-length] 规则，对于编写多行字符串，我们建议使用块样式指示符：由管道符 (|) 表示的字面样式或由直角括号 (>) 表示的折叠样式，而不是使用反斜杠转义换行符。请参阅指南，了解如何在 yaml 中编写多行字符串。

有问题的代码¶

# Missing YAML document start.
foo: 0777 # <-- yaml[octal-values]
foo2: 0o777 # <-- yaml[octal-values]
foo2: ... # <-- yaml[key-duplicates]
bar: ...       # <-- yaml[comments-indentation]

正确的代码¶

---
foo: "0777" # <-- Explicitly quoting octal is less risky.
foo2: "0o777" # <-- Explicitly quoting octal is less risky.
bar: ... # Correct comment indentation.

Yamllint 配置¶

如果您决定向项目中添加自定义 yamllint 配置，ansible-lint 可能会拒绝运行，如果它检测到您的某些选项不兼容，并要求您更正它们。发生这种情况时，您将看到如下消息

CRITICAL Found incompatible custom yamllint configuration (.yamllint), please either remove the file or edit it to comply with:
  - comments.min-spaces-from-content must be 1
  - braces.min-spaces-inside must be 0
  - braces.max-spaces-inside must be 1
  - octal-values.forbid-implicit-octal must be true
  - octal-values.forbid-explicit-octal must be true

Read https://docs.ansible.com/projects/lint/rules/yaml/ for more details regarding why we have these requirements.

警告

自动修复功能会将内联注释缩进更改为一个字符而不是两个，这是 yamllint 的默认设置。做出此决定的原因是保持与 prettier 的重新格式化兼容性，后者是最受欢迎的重新格式化工具。

.yamllint

rules:
  comments:
    min-spaces-from-content: 1 # prettier compatibility

无需创建此 yamllint 配置文件，但是如果您自己运行 yamllint，则可能需要创建它以使其行为与 ansible-lint 相同。

您可以在下面找到我们的 linter 在没有自定义文件时将使用的默认 yamllint 配置。

extends: default
rules:
  comments:
    # https://github.com/prettier/prettier/issues/6780
    min-spaces-from-content: 1
  # https://github.com/adrienverge/yamllint/issues/384
  comments-indentation: false
  document-start: disable
  # 160 chars was the default used by old E204 rule, but
  # you can easily change it or disable in your .yamllint file.
  line-length:
    max: 160
  # We are adding an extra space inside braces as that's how prettier does it
  # and we are trying not to fight other linters.
  braces:
    min-spaces-inside: 0 # yamllint defaults to 0
    max-spaces-inside: 1 # yamllint defaults to 0
  # key-duplicates:
  #   forbid-duplicated-merge-keys: true # not enabled by default
  octal-values:
    forbid-implicit-octal: true # yamllint defaults to false
    forbid-explicit-octal: true # yamllint defaults to false
  # quoted-strings:
  #   quote-type: double
  #   required: only-when-needed