基础设施即代码 / 系统课时
复用 Include 与 Import
复用 Include 与 Import
当任务文件或角色开始拆分后,真正容易踩坑的不是“怎么引用”,而是“什么时候展开”。本课用一个可运行实验对比动态 include 与静态 import,帮助你按运行时条件、循环需求和可预览性选择正确的复用方式。
学习目标
- 解释
include_*与import_*在展开时机上的根本差异。 - 根据运行时变量、循环、标签和任务可见性选择合适方式。
- 用最小 Playbook 验证静态导入与动态包含的实际执行结果。
先看两种复用的展开时机
ansible.builtin.include_tasks、ansible.builtin.include_role 属于动态复用:Ansible 执行到这条任务时,才决定要加载哪个任务文件或角色。因此,前面任务刚写入的事实、注册结果或循环项都可以参与选择。
ansible.builtin.import_tasks、ansible.builtin.import_role 属于静态复用:Ansible 在真正执行任务前先展开内容,后续执行看到的已经是导入后的任务。完整 Playbook 也只能通过 ansible.builtin.import_playbook 静态复用,没有对应的动态 include_playbook。

两者的核心差异可以压缩成下面几项:
| 关注点 | include_* |
import_* |
|---|---|---|
| 展开时机 | 执行到该任务时 | Playbook 执行前 |
| 运行时选择文件 | 适合 | 不适合 |
| 循环复用 | include_tasks、include_role 可配合循环 |
不用于循环导入 |
| 标签传播 | 默认只标记 include 本身;需要时用 apply 等方式传给内部任务 |
标签会应用到导入后的任务 |
--list-tasks / --list-tags |
动态内容通常无法在预处理阶段完整列出 | 导入后的内容可提前看到 |
用同一变量观察静态与动态结果
下面的实验先把 task_file 定义为 one.yml,运行时再用 set_fact 改成 two.yml。静态 import 在运行前已经解析文件名,而动态 include 会读取运行到该位置时的最新变量值。
mkdir -p /tmp/ansible-reuse
cd /tmp/ansible-reuse
cat > one.yml <<'YAML'
- name: Message from one
ansible.builtin.debug:
msg: "loaded one.yml"
YAML
cat > two.yml <<'YAML'
- name: Message from two
ansible.builtin.debug:
msg: "loaded two.yml"
YAML
cat > site.yml <<'YAML'
- name: Compare import and include timing
hosts: localhost
gather_facts: false
vars:
task_file: one.yml
tasks:
- name: Change task file at runtime
ansible.builtin.set_fact:
task_file: two.yml
- name: Static import resolved before task execution
ansible.builtin.import_tasks: "{{ task_file }}"
- name: Dynamic include resolved when reached
ansible.builtin.include_tasks: "{{ task_file }}"
YAML
ansible-playbook -i localhost, -c local site.yml预期输出中,静态导入仍执行 one.yml,动态包含则加载 two.yml。不同 ansible-core 版本的任务横幅格式可能略有差异,但关键消息应一致:
TASK [Change task file at runtime] ********************************
ok: [localhost]
TASK [Message from one] *******************************************
ok: [localhost] => {
"msg": "loaded one.yml"
}
TASK [Dynamic include resolved when reached] **********************
included: /tmp/ansible-reuse/two.yml for localhost
TASK [Message from two] *******************************************
ok: [localhost] => {
"msg": "loaded two.yml"
}这个结果说明:import 决定“任务图长什么样”,include 决定“运行到这里时再装入什么”。如果被引用文件名依赖前面任务产生的值,应优先考虑动态 include。
条件、循环与标签的边界
条件也会因展开方式不同而产生不同语义。条件写在 import_tasks 上时,会作用到导入后的各个任务;如果其中某个任务改变了条件依赖的变量,后续导入任务再次判断时可能得到不同结果。条件写在 include_tasks 上时,先决定这一刻是否执行包含动作,只有通过后才装入内部任务。
循环是动态 include 最典型的使用场景,例如按多个实例参数重复包含同一组任务。反过来,如果你希望 ansible-playbook --list-tasks、--list-tags 或 --start-at-task 尽可能看到稳定、完整的任务结构,静态 import 更合适。
按复用意图做选择
需要根据运行时事实、注册结果或循环项决定“加载什么”时,选择 include_tasks 或 include_role;被复用内容固定、希望任务在执行前完全展开时,选择 import_tasks 或 import_role;拆分完整 Playbook 时使用 import_playbook。
实际维护中,先问自己一句“这个引用目标能否在执行前确定”。能确定且希望任务结构透明,就偏向 import;必须等运行时才能决定,就使用 include。这样比记忆一长串语法差异更可靠。