playbook文件必须以.yml结尾且首行是---；yaml缩进用空格、冒号后加空格；hosts和gather_facts必设；调试用debug模块；执行前需--syntax-check和--check验证。

Playbook 文件必须以 .yml 结尾且首行是 ---

Ansible 不认 .yaml 以外的扩展名，也不接受没有文档分隔符的文件。常见错误是写成 deploy.sh 或直接叫 playbook，结果运行时报 ERROR! Syntax Error while loading YAML 或干脆提示 “no inventory found”。

• 文件名必须带 .yml 后缀，比如 web_setup.yml
• 第一行必须是 ---（三个短横线），不是 # 注释，也不是空行
• YAML 缩进必须用空格，不能用 Tab；2 空格或 4 空格都行，但同一层级要一致
• 冒号后必须跟一个空格，hosts:webservers 是错的，得写成 hosts: webservers

hosts 和 gather_facts 这两个字段最容易配错

很多人一上来就写任务，却忘了指定目标机器和是否收集系统信息。不设 hosts，Playbook 根本不执行；不关 gather_facts，在无 Python 环境（如容器、嵌入式）里会卡住甚至失败。

• hosts 必须对应 inventory 中定义的组名或 IP，比如 hosts: app_servers，不能写成 hosts: localhost（除非 inventory 显式声明了该别名）
• 如果只是跑本地命令或调试，用 hosts: localhost 并加 connection: local
• 对 Docker 容器、Alpine 镜像等轻量环境，务必加 gather_facts: false，否则 Ansible 会尝试调用 /usr/bin/python，而很多镜像根本没装 Python

用 debug 和 vars 调试比猜更可靠

Playbook 执行失败时，别急着改任务逻辑——先确认变量有没有、值对不对、路径存不存在。Ansible 没有“打印变量”语法糖，全靠 debug 模块显式输出。

• 查变量：加一个任务 - debug: var=ansible_hostname，立刻看到当前主机名
• 查自定义变量：定义 vars: 后，用 debug: var=my_app_port 验证是否生效
• 查路径是否存在：用 stat 模块 + debug 组合，比如 - stat: path=/etc/myapp.conf，再 debug: var=stat.stat.exists
• 变量作用域容易混淆：vars 在 play 级定义，set_fact 在 task 级生成，后者不能跨 play 使用

执行前必须用 ansible-playbook --syntax-check 和 --check

写完 Playbook 别直接 -t 上生产。YAML 语法错一个空格就整个挂掉；命令类任务（如 shell、command）不加 --check 模式，可能误删文件或重启服务。

• ansible-playbook web_setup.yml --syntax-check：只校验 YAML 和基本结构，秒出结果
• ansible-playbook web_setup.yml --check：跳过变更类操作（如 copy、service），只模拟执行路径
• --limit 加上目标主机，避免全量跑错；--start-at-task 可跳过前面已验证的部分
• 注意：--check 对 shell 和 command 默认不生效，得手动加 check_mode: no 才能强制跳过

真正麻烦的不是写错语法，而是变量插值位置不对、条件判断漏了引号、或者路径用了相对路径却没设 remote_user 权限——这些没法靠检查命令发现，得靠 debug 和小范围测试打点确认。