渲染失败的代价
模板引用的变量未定义时渲染会直接失败，任务一中断，这批主机的配置就停在半完成状态。容错手段分三层：给可选项提供默认值、区分变量未定义与变量为空值、以及把可选内容整段放进条件里。要留意默认值的副作用——它让渲染通过，却也可能把本应暴露的拼写错误掩盖成兜底配置。
基本信息
| 默认值 | 默认值过滤器，第二个参数决定空值是否也替换 |
|---|---|
| 存在性判断 | 变量是否存在测试，用于区分缺失与空值 |
| 关键参数校验 | 断言模块，缺失时主动失败并给出信息 |
| 可选段落 | 整段放进条件，避免渲染出空内容 |
典型使用场景
- 模板中给可选参数留默认：缺失时用合理缺省而不是中断渲染
- 区分变量未定义与变量是空值：按字段语义决定第二个参数怎么给
- 关键变量缺失要尽早失败：断言比渲染阶段报错更好定位
- 可选配置段落整体条件化：不适用时整段不输出
- 兼容不同版本的变量命名：先判断再用，避免一次改动打断所有主机
校验与容错
校验与容错
- name: 关键参数缺失时提前失败 # 比渲染时报错更好定位
ansible.builtin.assert:
that:
- nginx_port is defined
- nginx_port | int > 0
fail_msg: nginx_port 未定义或非法
- name: 未定义与空值分开处理 # 第二个参数控制空值是否替换
ansible.builtin.debug:
msg:
- "{{ srv_name | default('web01') }}"
- "{{ backup_dir | default('/var/backups', true) }}"写法与适用
| 写法 | 行为 | 适用场合 |
|---|---|---|
| 默认值过滤器 | 未定义时用替代值 | 可选参数 |
| 默认值加第二参数 | 未定义或空值时都用替代值 | 允许空值的可选字段 |
| 存在性测试 | 判断变量是否已定义 | 兼容不同命名约定 |
| 断言 | 条件不满足时主动失败 | 关键参数校验 |
对必须存在的参数用断言校验，对真正的可选项才用默认值。两者混用会让配置看起来正常，实际内容却是兜底值。
渲染失败往往发生在模板中后段，前面的文件可能已经落盘，机器处于半完成状态。批量变更前先在一台机器上演练一次，确认渲染能完整通过。
先校验再渲染
稳妥的编排顺序是：先用断言或调试任务把本次需要的变量检查一遍，确认取值与类型都符合预期，再执行模板落盘。这样失败信息指向缺失的变量而不是模板行号，排查时间按分钟算，而不是按配置文件逐行比对算。