先查文档再写任务
参数名记错、选项在版本间被改名、返回值字段不存在，这三类问题占了写 playbook 时的多数返工。ansible-doc 能在本地直接查已安装版本对应的文档，包括参数、默认值、可选值、返回值与官方示例，比凭记忆写更可靠，也比查网上的文章更贴近本机实际版本。
基本信息
| 查模块 | ansible-doc <模块名>，集合模块写全名如 ansible.builtin.copy |
|---|---|
| 列清单 | ansible-doc -l 列出全部模块，可配合分页工具过滤 |
| 看片段 | -s 或 --snippet 输出可直接粘贴的 YAML 任务片段 |
| 看其他类型 | 用 -t 指定类型（模块、插件、lookup 等），具体取值以官方文档为准 |
| 查集合 | 已安装集合的模块同样可查，需写命名空间前缀 |
| 版本对应 | 本地文档与安装的 ansible-core、集合版本一致，这是它比网页更可靠的原因 |
典型使用场景
- 写不熟悉的模块：先看必填参数与可选值列表，避免靠试错
- 升级后报参数不存在：用本地文档确认当前版本里的参数名与是否已废弃
- 需要任务骨架：用片段输出直接粘贴，减少缩进与格式错误
- 排查返回值：确认任务返回里到底有哪些字段，再决定 register 后怎么判断
- 区分同名模块：两个集合都有相似模块时，查文档确认各自参数差异
- 离线环境：无法访问外网文档站点，本地 ansible-doc 仍然可用
常用查法
常用查法
# 查看某个模块的完整文档
ansible-doc ansible.builtin.template
# 只输出可粘贴的任务片段
ansible-doc -s ansible.builtin.copy
# 列出全部模块，配合关键字过滤
ansible-doc -l | grep -i firewall
# 查已安装集合里的模块（命名空间必须写全）
ansible-doc community.general.ufw
# 确认本机版本，文档与它对应
ansible --version
ansible-galaxy collection list | head文档里的关键段落
| 段落 | 作用 | 判读要点 |
|---|---|---|
| 参数表 | 每个选项的类型、默认值、可选值 | 先看必填项，再看默认值是否符合预期 |
| 选项说明 | 取值约束与互斥关系 | 某些选项只在特定状态下生效，别只看名字猜 |
| 返回值 | register 之后能引用的字段 | 判断成功失败要基于实际返回字段 |
| 示例 | 官方用法样例 | 示例通常不覆盖边界，仍需结合参数说明 |
| 版本注记 | 新增或废弃的时间点 | 升级前逐项核对被标注为废弃的用法 |
网页版文档通常对应某个具体版本，而 ansible-doc 对应你机器上装着的那一个。排查“文档说是这个参数、执行却报不认识”时，优先相信本地输出，并核对 ansible-core 与集合的版本。
文档里的示例代码要结合自己的环境改造：示例中的路径、包名、服务名都是演示值，直接粘贴到生产 playbook 可能指向不存在的对象，或在错误的系统上执行包管理动作。
形成习惯
把查文档放在写任务之前而不是失败之后：先确认模块名与其必填参数，再确认返回值字段，最后照片段骨架填空。这个顺序能消掉大部分“参数名拼错”“选项在当前版本已改名”“register 后引用不存在的字段”这类低级返工。