Playbook执行失败时应分层排查：先看终端输出识别失败主机和任务，再用-v/vvv获取详细上下文，检查目标主机环境，最后用debug和register捕获中间状态并精确定义失败条件。

Playbook 执行失败时，关键不是“重跑一遍”，而是快速锁定哪台主机、哪个任务、什么环节出了问题。定位失败节点需要分层排查：从执行输出入手，结合日志、变量、模块行为逐级下钻。

看终端输出，识别失败主机和任务

Ansible 默认用颜色标记状态：红色代表失败（failed），黄色代表变更（changed），绿色代表无变化（ok）。失败行会明确标出主机名和任务名，并附带错误摘要。

• 重点关注 failed=1 或类似统计行，确认失败主机数量
• 失败任务下方通常有 JSON 格式错误详情，例如 "msg": "No package matching 'httpd' found" 或 "rc": 1（命令返回码）
• 若多台主机并行执行，失败可能只出现在部分节点——注意每台主机的独立结果块，不要只扫最后一屏

启用详细模式，获取上下文信息

加 -v（或 -vv、-vvv）运行，能暴露模块调用参数、远程命令实际执行路径、环境变量等隐藏细节。

• ansible-playbook site.yml -v 显示任务参数和基础连接信息
• -vvv 还会打印 SSH 连接调试、Python 解释器路径、模块临时文件位置，对权限、路径、解释器不兼容类问题极有用
• 特别注意 "module_stderr" 和 "module_stdout" 字段，它们是远程命令的真实输出，比 msg 更原始可靠

检查目标主机现场状态

失败常源于目标机环境异常，而非 Playbook 本身。可立即在对应主机上验证：

• SSH 是否通：ssh user@host -o ConnectTimeout=5
• Ansible 所用 Python 路径是否存在且可执行（如 /usr/bin/python3），可通过 ansible host -m setup -a "gather_subset=none" 快速确认
• 任务依赖的服务/端口/文件是否就绪（例如 yum 源是否可用、磁盘是否满、SELinux 是否阻止操作）
• 若任务含 shell 命令，登录后手动执行相同命令，观察真实报错（注意用户、环境变量、工作目录差异）

用 debug 和 register 捕获中间状态

当失败由前序任务输出引发（如 API 返回异常、文件内容不符合预期），需在关键点插入调试逻辑：

• 对任意任务加 register: result_var，再跟一个 - debug: var: result_var 查看完整返回结构
• 用 debug: msg: "{{ result_var.stdout }}" 提取特定字段，避免输出过长
• 配合 failed_when 精确定义失败条件，把模糊的“模块报错”转为清晰的业务判断（例如 failed_when: "'error' in result_var.stdout"）