unreachable! 错误主因是ssh连接配置异常，需手动验证ssh命令、检查ansible.cfg参数，并针对容器改用docker连接插件；空值判断应统一用is not defined or | default('') == ''；vault加密文件须以.yml.enc结尾并由ansible自动加载解密。
Ansible 执行报错 UNREACHABLE! 怎么快速定位
不是所有连不上都是网络问题，UNREACHABLE! 的真实原因往往藏在底层连接方式里。默认走 SSH，但如果你用的是非标准端口、密钥路径不对、或目标机没开 sshd，Ansible 会直接放弃并报这个错，不提示具体失败点。
实操建议：
- 先手动跑一遍 Ansible 底层用的 SSH 命令：
ssh -o ConnectTimeout=5 -o ConnectionAttempts=2 -i /path/to/key user@host -p 2222 -o StrictHostKeyChecking=no，看是否真能通 - 检查
ansible.cfg里remote_port、private_key_file、host_key_checking是否和实际环境一致 - 如果目标是容器或无 SSH 的轻量系统（比如某些 Alpine 镜像），别硬扛 SSH，改用
docker或community.docker.docker_connection插件
Playbook 里 when 判断变量为空总不生效
Ansible 的“空”有好几种：未定义（undefined）、空字符串（''）、空列表（[]）、null。直接写 when: my_var == '' 会因变量未定义而报错；写 when: my_var is not defined 又漏掉空字符串场景。
实操建议：
- 统一用
is none或is not defined+== ''组合判断：when: my_var is not defined or my_var | default('') == '' - 对列表/字典类变量，优先用
is iterable和length == 0，比如：when: my_list is iterable and my_list | length == 0 - 避免在
when中调用 filter（如default）以外的复杂表达式，Jinja2 解析阶段就可能出错，且错误信息极难定位
ansible-vault 加密后变量在 include_vars 中失效
不是 Vault 不起作用，而是 include_vars 默认不自动解密加密文件——它只负责加载 YAML/JSON，不解密逻辑由 Ansible 主流程控制。如果你把加密内容放在独立文件里再 include_vars，Ansible 会把它当普通字符串读入，后续引用时还是密文。
实操建议：
- 加密文件必须以
.yml.enc或.yaml.enc结尾，且确保ansible-vault版本与运行环境一致（不同版本间加密头格式有差异） - 不要在
include_vars后立刻用debug打印变量验证，因为debug默认不展开嵌套结构，看起来像没解密；改用debug: var=my_secret查看原始值 - 更稳妥的做法是：把敏感变量全收进
group_vars/all.yml或host_vars/xxx.yml，让 Ansible 在变量加载阶段自动识别并解密，而不是靠include_vars动态引入
用 copy 模块传大文件慢，又不想换 rsync
copy 模块本质是把文件 base64 编码后通过 SSH 传输，再在远端解码写盘，单次传输上限受 max_file_size 和 Python 内存限制影响，10MB 以上就明显卡顿，还容易触发超时。
实操建议：
- 优先启用
transfer_method: sftp（Ansible 2.8+ 默认），比 base64 快 3–5 倍，且支持断点续传 - 若目标主机禁用了 SFTP，可在
ansible.cfg中强制开启：sftp_batch_mode = False，避免批量传输时反复握手 - 真正的大文件（>100MB）别硬塞进 Playbook，改用
get_url+ 远端 URL 下载，或提前推到 NFS/S3，Playbook 只负责拉取和校验
remote_user、一次没清掉的 ~/.ansible/cp/ 缓存、或者某台机器上被运维手动改过 /etc/ansible/ansible.cfg。这些地方不会报错，但会让结果变得不可预测。 
