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 和小范围测试打点确认。
