如何在Ansible 2.9.6中本地导入未打包的自定义集合角色？

针对你遇到的Ansible 2.9.6无法找到集合内角色的问题，我来一步步帮你解决——毕竟2.9作为较早支持集合的版本，在本地集合的路径要求和角色引用上有不少需要注意的细节，和新版本略有不同。

一、先修正本地目录结构（核心！） #

Ansible 2.9对未通过ansible-galaxy安装的本地集合，有严格的目录层级要求：集合必须放在collections/ansible_collections/<namespace>/<collection_name>这个路径下，缺少中间的ansible_collections目录是最常见的错误根源。

你原来的目录结构需要调整为：

.
├── collections
│   └── ansible_collections
│       └── test  # 对应你galaxy.yml里的namespace
│           └── ansible_poc_collection  # 对应galaxy.yml里的name
│               ├── docs
│               ├── galaxy.yml
│               ├── plugins
│               │   └── README.md
│               ├── README.md
│               └── roles
│                   └── testrole
│                       └── tasks
│                           └── main.yml
└── test-play.yml

如果想保留原来的test目录，也可以把collections目录放在test下，后续通过环境变量指定路径即可。

二、正确引用角色（避免模糊匹配） #

在Ansible 2.9中，即使你在playbook里指定了collections列表，导入角色时最好使用完整的FQCN（全限定集合名称），这样能绕过可能的路径查找优先级问题。修改你的test-play.yml：

- hosts: all
  collections:
    - test.ansible_poc_collection
  tasks:
    - import_role:
        name: test.ansible_poc_collection.testrole  # 使用完整的角色FQCN

如果后续目录结构完全正确，也可以简化为name: testrole，但用FQCN能最大程度避免查找异常。

三、指定集合查找路径（可选，确保Ansible能找到你的集合） #

如果你的collections目录不在默认查找路径里，可以通过两种方式指定：

1. 环境变量方式：在运行playbook前执行

   export COLLECTIONS_PATHS=/path/to/your/project  # 注意这里是包含collections目录的父目录，不是collections本身
   

2. ansible.cfg配置方式：在项目根目录创建或修改ansible.cfg，添加：

   [defaults]
   collections_paths = ./collections:/home/user/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
   

   这里的./collections就是你刚才调整后的顶层collections目录的相对路径。

四、验证集合是否被识别 #

运行以下命令确认Ansible能找到你的本地集合：

ansible-galaxy collection list

如果输出里能看到test.ansible_poc_collection，说明路径配置正确，此时再运行你的playbook应该就能正常找到角色了。

补充：为什么之前的尝试失败？ #

• 你把集合移到顶层collections目录，但大概率没创建ansible_collections中间目录，Ansible 2.9不会直接识别collections目录下的集合文件夹；
• 使用完整角色名但路径结构不对的话，Ansible还是找不到对应的集合位置；
• COLLECTIONS_PATHS需要指向包含collections目录的父目录，而不是集合本身的目录，这也是容易踩的坑。

内容的提问来源于stack exchange，提问作者Lion