为何我的Ansible模板文件未完成变量替换？

问题现象 #

使用Ansible的template模块部署配置文件时，远程机器生成的文件完全保留模板中的变量占位符（如{{ teamcity_url }}），未完成变量替换。Ansible执行无报错，且在模板任务前已确认所需变量确实存在。

相关代码 #

Ansible任务片段 #

- name: "为{{ agent_name }}生成buildAgent.properties"
  template:
    src: buildAgent.properties.j2
    dest: "{{ config_path }}/buildAgent.properties"

Jinja2模板文件（buildAgent.properties.j2） #

serverUrl={{ teamcity_url }}
name={{ agent_name }}

{% if teamcity_agent_variables %}
{% for variable in teamcity_agent_variables %}
{{ variable }}={{ teamcity_agent_variables[variable] }}
{% endfor %}
{% else %}
# 未从Ansible获取到teamcity_agent_variables
{% endif %}

环境信息 #

Ansible版本 #

% ansible --version                                      
ansible [core 2.13.3]
  config file = /Users/timb/git/mre-ansible/ansible.cfg
  configured module search path = ['/Users/timb/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/Cellar/ansible/6.3.0/libexec/lib/python3.10/site-packages/ansible
  ansible collection location = /Users/timb/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.10.6 (main, Aug 30 2022, 05:12:36) [Clang 13.1.6 (clang-1316.0.21.2.5)]
  jinja version = 3.1.2
  libyaml = True

关键配置项 #

% grep error_on  /Users/timb/git/mre-ansible/ansible.cfg

#error_on_missing_handler = True
error_on_undefined_vars = True

排查与解决方案 #

• 验证模板文件扩展名：确保模板文件后缀为.j2，Ansible默认仅识别该后缀的文件作为Jinja2模板解析。若文件名错误（如省略.j2），模块会直接复制原文件而不处理变量。
• 确认变量作用域：检查变量的定义位置（vars块、host_vars/group_vars、set_fact结果等），确保当前任务所在的play或角色能正确读取到变量。
• 本地调试模板渲染：添加临时调试任务，在控制节点本地渲染模板，验证变量替换是否正常：

  - debug:
      msg: "{{ lookup('template', 'buildAgent.properties.j2') }}"
  

  若本地渲染正常，说明问题出在远程文件传输或权限；若本地也未替换，重点排查变量解析逻辑。
• 检查变量特殊字符：若变量包含Jinja2特殊字符（如{、}、%），需使用{{ variable | escape }}进行转义，避免解析异常。
• 查看详细执行日志：添加-v/-vvv参数执行playbook，从日志中查看模板解析阶段的细节，确认是否存在隐性错误（如变量名拼写错误、类型不匹配）。

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