推荐手动创建标准Ansible角色目录结构，如roles/nginx/{tasks,handlers,templates,files,vars,defaults,meta}并初始化各main.yml文件，确保覆盖全部核心子目录，满足变量分层、模板隔离与依赖声明等生产要求。
直接创建标准 Ansible 角色目录结构，推荐手动构建而非依赖 ansible-galaxy init —— 因为自动生成的结构常含冗余文件、命名不一致，且默认不包含 defaults/ 和 meta/ 等关键子目录，不利于企业级复用和变量分层管理。
标准角色目录结构及创建命令
以角色名 nginx 为例，在项目 roles/ 目录下执行：
mkdir -p roles/nginx/{tasks,handlers,templates,files,vars,defaults,meta}touch roles/nginx/tasks/main.yml roles/nginx/handlers/main.yml roles/nginx/vars/main.yml roles/nginx/defaults/main.yml roles/nginx/meta/main.yml
该结构覆盖 Ansible 官方定义的全部核心子目录，满足变量外置、模板隔离、依赖声明等生产要求。注意：files/ 存放静态文件（如二进制、配置备份），templates/ 专用于 .j2 Jinja2 模板，二者不可混用。
各目录用途与必须性说明
每个子目录承担明确职责，缺一不可：
- tasks/main.yml：唯一入口任务文件，只写本角色主干逻辑；禁止嵌套 include 或跨角色调用
-
handlers/main.yml：仅定义本角色可触发的 handler，命名建议带前缀（如
restart nginx service），避免与其他角色冲突 -
defaults/main.yml：提供安全兜底变量（如
nginx_listen_port: 80），可被group_vars或host_vars覆盖 -
vars/main.yml：存放内部计算变量（如
nginx_conf_dir: "{{ nginx_install_path }}/conf"），不对外暴露，不建议覆盖 -
meta/main.yml：声明角色依赖（如
dependencies: [{ role: common }]）和平台兼容性（galaxy_info），是组合复用的基础
路径位置与加载优先级
Ansible 按以下顺序查找角色：
- 当前 playbook 所在目录下的
roles/子目录（最高优先级，适合项目专属角色） -
ansible.cfg中roles_path配置的路径（如/etc/ansible/roles:/home/user/.ansible/roles，冒号分隔） - 系统默认路径（
/usr/share/ansible/roles，通常存放 RHEL 系统角色）
建议将通用角色统一放在 /etc/ansible/roles，项目专用角色保留在 playbook 同级 roles/ 下，避免路径混乱。
验证结构是否合规
运行以下命令检查基本完整性：
-
ls -R roles/nginx/ | grep ":$" | sed 's/:$//'—— 确认所有必需子目录存在 -
ansible-playbook site.yml --syntax-check -v—— 若引用该角色后无报错，说明结构被正确识别 - 执行
ansible-doc -t role nginx（需已注册）可查看角色文档元信息，前提是meta/main.yml已填写完整
结构对了，后续变量分层、依赖管理和跨环境复用才有坚实基础。
