ansible中fail模块配合msg参数可输出清晰错误提示，支持变量引用和多行文本，需用冒号格式并结合when条件触发，避免模糊表述，提供可操作线索。
在Ansible中用fail模块配合msg参数，就能在部署中断时输出清晰、可定位的错误提示，直接帮助运维快速判断失败原因，减少排查时间。
用fail模块加msg输出定制化报错
fail模块专为“主动失败”设计，不执行任何远程操作，只负责终止当前playbook并抛出信息。关键在于msg字段——它支持变量引用、字符串拼接和多行文本，让提示真正贴合上下文。
- 基础写法：
fail: msg: "数据库服务未就绪，跳过应用部署" - 带变量示例：
fail: msg: "主机 {{ inventory_hostname }} 的磁盘使用率 {{ df_result.stdout_lines[1].split()[4] | regex_replace('%','') | int }}% 超过阈值90%"（需先用command或shell获取df结果） - 避免语法错误：不要写成
fail: msg="xxx"（等号+双引号），应统一用冒号+空格+引号格式，如fail: msg: "xxx"
结合when条件触发精准中断
单纯执行fail没意义，必须搭配when做条件判断，才能实现“该停才停”。常见场景包括检查服务状态、端口连通性、文件存在性、变量是否为空等。
- 检查变量是否缺失：
fail: msg: "[ERROR] 变量 app_version 未定义，请检查group_vars或命令行传参" when: app_version is not defined - 验证前置服务可用性：
uri: url: http://localhost:8080/health status_code: 200 register: health_check fail: msg: "后端健康检查失败，HTTP {{ health_check.status }} {{ health_check.msg }}" when: health_check.status != 200 - 确认配置文件已生成：
stat: path: /etc/myapp/config.yml register: cfg_stat fail: msg: "配置文件 /etc/myapp/config.yml 缺失，无法启动服务" when: not cfg_stat.stat.exists
配合register与ignore_errors做柔性控制
有些任务本身可能失败（比如尝试连接一个尚未启动的服务），但你不想整条playbook直接退出，而是想捕获结果再决定是否fail。这时要用register存结果 + ignore_errors: true跳过默认中断。
- 先执行并忽略错误：
command: curl -s --head http://db:5432 | head -1 register: db_test ignore_errors: true - 再根据返回判断：
fail: msg: "数据库端口检测超时或拒绝连接，请检查网络策略与服务状态" when: db_test.rc != 0 or '200' not in db_test.stdout - 注意：
ignore_errors: true必须显式声明，否则任务一失败就终止，后续fail根本不会运行
错误信息要包含可操作线索
好的msg不是报错，而是给运维下一步动作的指引。避免模糊表述，优先包含：具体主机、涉及路径/端口/服务名、建议检查项、关联日志位置。
- 差的写法：
"服务启动失败" - 好的写法：
"Nginx 启动失败（systemctl start nginx 返回 code 1），请检查 /var/log/nginx/error.log 及配置语法：nginx -t" - 进阶技巧：用
stdout/stderr内容截取关键片段，例如{{ cmd_result.stderr | truncate(200) }}，避免日志刷屏又保留线索
