两道不同的检查
语法检查（--syntax-check）回答“这个 playbook 能不能被解析”：YAML 结构是否合法、缩进是否一致、引用的角色与任务文件是否存在。规范校验（ansible-lint，需另行安装）回答“写法是否可靠”：命令类任务有没有幂等条件、文件权限有没有显式声明、模块用法是否被推荐替代。两者互补，前者几秒就能跑，后者能拦住经验教训类的坑。
基本信息
| 语法检查 | ansible-playbook -i inventory site.yml --syntax-check |
|---|---|
| 结构预览 | --list-tasks 顺带验证任务结构是否合理 |
| 规范校验 | ansible-lint，独立工具，需按官方方式安装 |
| YAML 检查 | yamllint，检查缩进、行长、重复键等格式问题 |
| 运行前提 | 语法检查需要能读到清单与角色目录，不连目标机也不执行任务 |
| 接入位置 | 提交前钩子与流水线的第一道门禁 |
典型使用场景
- 提交前自检：改完 playbook 立刻跑一次语法检查，避免低级错误进仓库
- 流水线门禁：把语法检查与规范校验作为合并前置条件
- 接手排查：别人的 playbook 跑不起来，先确认能否通过解析，排除结构问题
- 批量迁移后核对：升级 Ansible 版本后集中跑一遍，找出被废弃的写法
- 编辑器集成：保存时自动检查，问题在写作当场暴露
- 评审辅助：把规范校验结果作为评审依据，减少人工盯格式
常见失败与修法
常见失败与修法
# 1) 变量开头未加引号会被当成 YAML 结构
- name: 错误示例
ansible.builtin.debug:
msg: {{ app_version }} # 解析报错
- name: 正确示例
ansible.builtin.debug:
msg: "{{ app_version }}" # 整体加引号
# 2) 值里含冒号必须加引号，否则被切成键值对
- name: 带冒号的值
ansible.builtin.debug:
msg: "提示：请看 /etc/app/app.conf"
# 3) 缩进必须用空格，制表符会导致解析失败；同层同级保持一致
# 命令与检查
# ansible-playbook -i inventory site.yml --syntax-check
# ansible-lint site.yml检查项与能拦住什么
| 检查 | 能发现 | 发现不了 |
|---|---|---|
| --syntax-check | YAML 结构错误、角色与任务文件缺失、缩进不一致 | 逻辑错误、参数名拼错、变量未定义 |
| ansible-lint | 缺幂等条件、缺权限声明、不推荐的模块用法 | 环境相关的运行期失败 |
| yamllint | 格式与风格问题 | 语义问题 |
| --check 预演 | 部分的变量与模板问题 | 命令类任务的实际效果 |
语法检查不连目标机，因此不能替代任何验证：它能保证“语法上可解析”，模块参数是否正确、变量是否存在、条件是否成立都要靠真实执行或检查模式来暴露。
规范校验工具会随版本更新规则集：升级后可能新增若干告警。建议先把规则集与忽略项固定在仓库里，再逐步收敛，避免某次升级后门禁哗啦啦全红、团队索性绕过检查。
顺序与收益
把语法检查放在最前面（代价最低、反馈最快），规范校验放在其后（拦住常见缺陷），再进检查模式预演，最后才真实执行。这一串顺序的收益是：绝大多数低级错误在动到任何主机之前就被拦下，执行阶段的失败集中在真正的环境问题上。