旧 playbook 适配 Ansible 新版本的核心是显式声明模块全限定名（FQCN）并检查远程执行环境。虽然 raw 模块本身未被移除，但 Ansible 2.10 引入集合（Collections）架构后，隐式模块解析行为发生变化，可能导致旧写法在严格模式下失效或行为不一致。

命令速用版

若 playbook 中原本使用 raw 模块执行命令，建议按以下格式更新配置片段，确保在新版本中稳定运行。

- name: Run legacy raw command
  ansible.builtin.raw:
    cmd: "yum install -y httpd"
    executable: /bin/bash

如果旧 playbook 未指定集合名称，直接在模块名前添加 ansible.builtin. 前缀即可解决大部分解析错误。

为什么会这样

Ansible 2.10 版本开始重构模块加载机制，将核心模块移入 ansible.builtin 集合，旧版隐式调用方式在新环境中可能被拦截或警告。raw 模块依赖 SSH 直接执行，不依赖远程 Python 环境，但新版本对 shell 解释器路径的默认假设更严格，未显式指定 executable 时可能因远程系统缺少 /bin/sh 而失败。公开资料中没有看到可靠的量化数据表明具体失败比例，但生产环境中混合操作系统场景风险较高。

分步处理

第一步：备份现有 playbook 文件，防止修改后无法回滚。

第二步：全局替换模块名，将 raw 替换为 ansible.builtin.raw，可使用 sed 命令批量处理：

sed -i 's/^[[:space:]]*raw:/  ansible.builtin.raw:/g' playbook.yml

第三步：检查涉及特权升级的任务，raw 模块在部分旧版本中对 become 支持不一致，新版本需显式确认 become: yes 是否生效。

第四步：为涉及非 Linux 系统或自定义 shell 的任务添加 executable 参数，避免默认 shell 解析错误。

怎么验证是否生效

使用检查模式运行 playbook，观察任务是否被正确识别为 ansible.builtin.raw 模块。

ansible-playbook -i inventory.ini playbook.yml `--check` -v

查看输出日志，确认没有模块未找到（Module not found）或解析警告。若远程主机执行失败，检查 ansible-playbook 输出中的 stderr 信息，确认是否为 shell 路径错误。

常见坑

部分旧 playbook 依赖 raw 模块绕过 Python 依赖安装，升级后若误用 command 模块会导致前置引导任务失败。raw 模块不支持 creates 或 removes 参数，若旧代码中混用需移除相关参数。在 Windows 远程主机上使用 raw 模块需确保 WinRM 配置允许直接命令执行，否则应改用 win_command 模块。

常见问题

必须使用 ansible.builtin.raw 吗？

在 Ansible 2.10+ 环境中建议必须使用，否则可能触发弃用警告或在严格模式下报错。

raw 模块还需要远程安装 Python 吗？

不需要，raw 模块通过 SSH 直接执行命令，适用于无法安装 Python 的初始环境。

升级后 raw 任务变慢是什么原因？

公开资料中没有看到可靠的量化数据表明性能变化，通常与 SSH 连接复用配置或控制节点负载有关，建议检查 ansible.cfg 中的 ssh_args 设置。

参考来源

• Ansible Documentation, ansible.builtin.raw module, https://docs.ansible.com/ansible/latest/collections/ansible/builtin/raw_module.html
• Ansible Release Notes, Ansible 2.10 Release Summary, https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html