Ansible自定义模块本质是返回标准JSON的可执行脚本，无需客户端安装，仅需目标主机具备对应解释器；基本结构包括声明解释器、导入AnsibleModule、调用exit_json或fail_json；存放于playbook目录下library子目录优先调用，支持参数校验、幂等性及--check模式。
Ansible 自定义模块本质是可执行脚本，只要能被 Python 解析、返回标准 JSON 格式结果，就能作为模块使用。它不依赖 Ansible 客户端安装，也不需要远程主机有额外环境——只需目标主机有对应解释器（如 Python、Bash、Perl 等）。
模块编写的基本结构
一个最小可用的自定义模块需满足三点：
- 以 #!/usr/bin/env python3（或 bash/other）开头，声明解释器
- 导入 AnsibleModule 类（来自 ansible.module_utils.basic）
- 调用 module.exit_json() 或 module.fail_json() 返回结构化结果
例如，一个检查文件是否存在并返回大小的简单 Python 模块 file_info.py：
#!/usr/bin/env python3
from ansible.module_utils.basic import AnsibleModule
import os
<p>def main():
module = AnsibleModule(
argument_spec=dict(
path=dict(type='str', required=True)
),
supports_check_mode=True
)
path = module.params['path']
if not os.path.exists(path):
module.fail_json(msg=f"File {path} does not exist")
size = os.path.getsize(path)
module.exit_json(changed=False, size=size, path=path)</p><p>if <strong>name</strong> == '<strong>main</strong>':
main()</p>存放位置与调用方式
模块文件需放在 Ansible 能识别的路径中，优先级从高到低为：
- 当前 playbook 所在目录下的 library/ 子目录（推荐，项目隔离）
- 全局配置中 library 参数指定的路径（如
/usr/share/ansible/library） - 通过 ANSIBLE_LIBRARY 环境变量设置的路径
存好后，在 playbook 中直接像内置模块一样使用：
- name: Get file info
file_info:
path: /etc/hosts支持参数校验与幂等性
AnsibleModule 支持完整参数定义，包括类型、默认值、必需性、选择范围等：
-
type='int'或'bool'自动做类型转换和校验 -
choices=['started', 'stopped']限制合法取值 -
required_if=[['state', 'present', ['name']]实现条件依赖 -
supports_check_mode=True启用--check模式，模块内需判断module.check_mode并跳过实际变更
调试与验证技巧
避免反复跑 playbook 浪费时间：
- 用
python3 file_info.py -a 'path=/etc/hosts'直接运行模块，查看原始输出 - 加
-vvv参数运行 ansible 命令，看模块传入参数和 stdout/stderr 细节 - 用
ansible-doc -t module file_info查看自动提取的文档（需模块含DOCUMENTATION字符串） - 在模块开头加
import traceback; traceback.print_exc()快速定位异常位置
