为什么要写全名
集合是模块、插件与角色的分发单位，命名形如“命名空间.名称”：命名空间代表组织，名称代表这一套内容的主题。写任务时用全名调用（命名空间.集合.模块）能消除歧义——同名模块可能来自核心与第三方集合，不写全名时由查找顺序决定用哪个，出问题时很难判断实际执行的是谁。
基本信息
| 调用写法 | 命名空间.集合名.模块名，核心内容使用内置命名空间 |
|---|---|
| 依赖声明 | 用需求文件列出集合与版本约束，安装时按它拉取 |
| 安装位置 | 默认安装到用户或系统目录，项目内也可放集合目录由查找路径发现 |
| 查看现状 | 用列表命令看已装集合与版本，便于确认实际使用哪一份 |
| 简写风险 | 集合关键字可缩短模块名书写，但插件类型覆盖范围有限，具体以官方文档为准 |
| 版本绑定 | 同一集合的不同版本行为可能不同，必须锁定版本 |
典型使用场景
- 引用第三方能力：网络设备、云平台、容器相关的模块几乎都在集合里
- 区分同名模块：明确指向核心实现或集合实现，避免查找顺序带来的歧义
- 团队统一版本：需求文件锁定集合版本，保证所有人执行结果一致
- 项目自包含：把依赖装在项目内目录，与系统环境隔离
- 升级评估：先看集合版本变更说明，再决定升级时机
- 离线交付：提前把集合下载好随项目分发，避免目标环境无法联网
写法与依赖管理
写法与依赖管理
# 用全名调用（推荐）
- name: 用核心模块写文件
ansible.builtin.copy:
src: app.conf
dest: /etc/app/app.conf
- name: 用集合里的网络模块
cisco.ios.ios_config:
lines:
- hostname sw1
# 需求文件 roles_requirements.yml / requirements.yml
# collections:
# - name: community.general
# version: ">=8.0.0,<9.0.0"
# - name: ansible.posix
# version: "1.5.4"
# roles:
# - name: geerlingguy.nginx
# version: "3.1.4"
# 安装与核对
# ansible-galaxy collection install -r requirements.yml
# ansible-galaxy collection list | head -20命名与查找
| 写法 | 含义 | 注意点 |
|---|---|---|
| 命名空间.集合.模块 | 全名调用，指向唯一实现 | 推荐在新剧本中统一使用 |
| 仅模块名 | 按查找顺序解析 | 同名冲突时实际执行对象不确定 |
| 内置命名空间 | 核心自带的模块与插件 | 升级核心版本时行为可能变化 |
| 项目内集合目录 | 随项目分发的集合 | 需确保查找路径能发现它 |
| 需求文件版本约束 | 声明依赖范围 | 不写约束就等于接受上游任何变更 |
简写关键字能少敲前缀，但对过滤器、测试、查找类插件的覆盖并不完整（这部分限制随版本变化，以官方文档为准）。追求确定性的项目直接写全名最省心，代价只是多几个字符。
依赖不锁版本的后果是“同一份代码在不同时间执行结果不同”：上游发布新版后行为变化，排障方向会被带偏。需求文件里给出明确版本或范围，并在变更时按记录评估影响。
落地习惯
新项目一建立就写好需求文件并在文档里说明安装命令；剧本中一律使用全名；升级集合时先在测试清单上跑一遍，再看变更说明。这三条习惯能消掉大部分“为什么他那里能跑、我这里报错”的沟通成本。