Ansible自定义变量文件使用报错：未知变量问题排查与实现方法

首先，unknown variable的核心原因是你的自定义变量文件没有被Ansible正确加载，或者变量的引用路径/拼写存在问题。下面结合你提到的文件结构（vars/var1.yml、vars/var2.yml、task.yml），一步步说明正确配置方法和排错思路：

1. 先确认变量文件的格式合规 #

首先检查你的var1.yml/var2.yml是不是标准的YAML格式，变量定义必须用冒号而非等号：

错误示例：

my_var = "hello"  # 用了等号，不符合YAML规范

正确示例：

my_var: "hello"
my_service_port: 8080
my_server_list:
  - 192.168.1.10
  - 192.168.1.11

2. 在Playbook中显式加载变量文件 #

如果你的task.yml是一个完整的Playbook（包含- hosts:结构），需要在Play级别通过vars_files字段指定要加载的变量文件，这样Ansible执行时才会先读取这些变量：

# task.yml
- hosts: your_target_hosts  # 替换成你的目标主机组/主机
  vars_files:
    - ./vars/var1.yml  # 用相对路径指向变量文件，相对于task.yml的位置
    - ./vars/var2.yml
  tasks:
    - name: 测试自定义变量
      debug:
        msg: "我的变量值是: {{ my_var }}，端口是{{ my_service_port }}"

3. 命令行临时加载变量文件 #

如果不想在Playbook里硬编码变量文件路径，也可以通过命令行参数临时加载：

ansible-playbook task.yml -e @vars/var1.yml -e @vars/var2.yml

注意这里的@符号是必须的，用来告诉Ansible后面跟着的是变量文件路径，而非直接的键值对。

4. 基于Roles的自动加载（若使用Roles架构） #

如果你的项目是用Roles组织的，可以把变量文件放到roles/your_role/vars/目录下，Ansible会自动加载该目录下的所有YAML文件，无需额外配置vars_files：

your_project/
├── roles/
│   └── my_web_role/
│       ├── vars/
│       │   ├── var1.yml
│       │   └── var2.yml
│       └── tasks/
│           └── main.yml  # 这里可以直接引用var1.yml里的变量
└── task.yml

常见排查要点 #

• 路径错误：确保vars_files里的路径是相对于Playbook（task.yml）的相对路径，或者用绝对路径。如果路径写错，Ansible找不到文件，自然加载不了变量。
• 拼写大小写：YAML是大小写敏感的，检查tasks里引用的变量名和变量文件里的定义是否完全一致（比如MyVar和myvar是两个不同的变量）。
• 作用域问题：如果变量是在某个Role的vars目录下，仅能在该Role的tasks中使用；如果要全局使用，需要放到group_vars/host_vars目录，或者通过vars_files全局加载。

按照上面的方法调整后，应该就能解决unknown variable的报错了。

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