hash_behaviour是Ansible中控制字典变量合并方式的配置项,取值replace(默认,完全替换)或merge(递归键级合并),仅在ansible.cfg中全局设置,推荐用combine过滤器替代。

hash_behaviour 是 Ansible 配置中控制字典(即哈希)类型变量合并方式的关键选项,仅影响 vars、host_vars、group_vars 等 YAML 字典变量的覆盖逻辑,不作用于列表或标量值。它有两个合法取值:replace(默认)和 merge,决定同名字典变量在多处定义时如何“叠加”。
hash_behaviour = replace(默认行为)
后加载的变量字典会**完全替换**先加载的同名字典,不进行键级合并。例如:
- 在
group_vars/all.yml中定义:nginx: {port: 80, ssl: false} - 在
host_vars/web01.yml中定义:nginx: {ssl: true} - 最终
web01主机上nginx的值为{ssl: true}——port: 80被丢弃。
hash_behaviour = merge(需显式启用)
后加载的字典会与先加载的同名字典进行**递归键级合并**(深合并),仅覆盖已存在的键,保留未冲突的键。上例中,若设为 merge,则 web01 上 nginx 结果为:{port: 80, ssl: true}。
注意:此合并仅限一层嵌套字典;Ansible 2.0+ 对深层嵌套支持有限,复杂结构建议用 combine 过滤器替代。
如何设置 hash_behaviour
该选项只能在 Ansible 配置文件中全局生效,不能在 playbook 或命令行中覆盖。启用方式如下:
- 编辑配置文件(如
/etc/ansible/ansible.cfg或当前目录下的ansible.cfg) - 在
[defaults]段取消注释并修改:hash_behaviour = merge - 保存后,所有后续运行的 playbook 和 ad-hoc 命令均按此规则解析字典变量
实际使用建议
除非有明确的多层配置继承需求(如基础服务参数 + 主机特化开关),否则不建议全局启用 merge。原因包括:
- 行为不易追踪,容易引发意外覆盖或遗漏
- 与 Ansible 2.12+ 推荐的
combine过滤器(显式、可控、支持 deep 参数)相比,缺乏灵活性 - 未来版本中该选项可能被弃用(官方文档已标记为 legacy)
更推荐的做法是:保持 hash_behaviour = replace 默认值,改用 {{ dict1 | combine(dict2, recursive=true) }} 在模板或 vars 中按需合并。


















