Ansible Role Requirements 通过 requirements.yml 显式声明、集中管控和版本锁定第三方角色，实现 CI 环境高度解耦；该文件须置于项目根目录，含 name、src（可选）、version（推荐）、scm（src 存在时必填）字段；CI 构建前执行 ansible-galaxy install -r requirements.yml -p roles/ 自动安装；Playbook 中仅引用角色名，依赖来源与路径完全透明；需确保角色含 tasks/main.yml、环境变量外置、禁用硬编码路径引用。
用 Ansible Role Requirements 管理第三方角色，是实现 CI 环境高度解耦的关键一环。它把外部依赖显式声明、集中管控、版本锁定，避免硬编码、手动下载或环境差异导致的部署不一致。
明确 requirements.yml 文件结构与位置
requirements.yml 是 Ansible 识别第三方角色的唯一入口文件，必须放在项目根目录或 roles/ 目录下（推荐放项目根目录）。内容需严格遵循 YAML 格式，每个角色条目至少包含 name 字段：
-
name：角色在 Galaxy 上的唯一标识，如
geerlingguy.nginx -
src（可选）：非 Galaxy 角色时指定 Git 地址，如
https://github.com/your-org/ansible-role-mysql.git -
version（强烈建议）：指定 tag、branch 或 commit，例如
v4.2.0或main，确保 CI 每次拉取一致代码 -
scm（仅 src 存在时需要）：值为
git
示例：
─ requirements.yml
---<br>- name: geerlingguy.nginx<br> version: "4.2.0"<br>- name: community.mysql<br> version: "3.9.0"<br>- name: your-internal-redis<br> src: https://git.yourcorp.com/ansible/roles/redis.git<br> scm: git<br> version: v1.3.5
在 CI 流程中自动安装依赖
每次 CI 构建开始前，执行 ansible-galaxy install -r requirements.yml -p roles/。这会将所有声明的角色下载并解压到本地 roles/ 目录下，供后续 playbook 调用。
-
-p roles/ 指定安装路径，必须与 playbook 中
roles_path配置或默认路径一致 - CI 节点无需预装任何角色，完全由该命令驱动，实现“一次声明、处处可用”
- 若使用容器化 CI（如 Jenkins Agent 或 GitHub Actions runner），可在构建镜像阶段就执行此命令，加快运行时速度
Playbook 中只声明角色名，不关心来源
主 playbook（如 deploy-ci.yml）只需写明要调用的角色名称，无需路径、URL 或版本信息：
-
roles:
- geerlingguy.nginx
- community.mysql
- your-internal-redis - Ansible 运行时自动在
roles/下查找对应子目录，完全屏蔽了角色是来自 Galaxy、Git 还是本地开发的细节 - 不同环境（dev/staging/prod）共用同一份 requirements.yml 和 playbook，仅通过
-e env=staging切换变量，真正实现配置与逻辑分离
规避常见陷阱，保障 CI 稳定性
高度解耦的前提是稳定可靠。以下三点必须检查：
- 所有 role 必须含
tasks/main.yml，否则ansible-playbook执行时报错role 'xxx' was not found - 不要在 role 内硬编码环境相关值（如数据库密码、API 地址），统一由
group_vars/ci.yml提供，再通过include_vars或vars_files加载 - 禁止在 playbook 中用
import_role+name: ./roles/xxx绕过 requirements —— 这等于把外部依赖又写死进代码，破坏解耦目标
