Terraform 模块故障排除指南

Source: Dev.to

症状

• 错误： 参数 "variable_name" 在此处不被期待
• 错误： 此对象没有名为 "output_name" 的属性
• 即使变量/输出看起来已正确定义，这些错误仍然会出现。

根本原因与解决方案

1. 过期的 Terraform 模块缓存 (最常见)

当您修改模块变量或输出时，Terraform 可能会使用缓存的信息。

使用时机： 在对以下任意内容进行更改后：

• 模块变量（variables.tf）
• 模块输出（outputs.tf）
• 模块源路径

解决方案： 清除缓存并重新初始化。

2. 空文件或损坏文件 (关键问题)

文件可能存在，但内容为 0 字节。

检查方法： 查找 Length: 0 或 0 bytes 的文件。

解决方案： 使用命令行（或编辑器）重新创建文件，以确保正确保存。

3. 缺少变量定义

Terraform 报告模块的 variables.tf 中不存在某个变量。

解决方案： 将缺失的变量添加到 modules//variables.tf。

添加后，清除缓存并重新初始化（参见解决方案 #1）。

4. 缺少输出定义

模块未公开所引用的输出。

解决方案： 将输出添加到 modules//outputs.tf：

output "output_name" {
  description = "Description"
  value       = azurerm_resource.resource_name.id
}

然后清除缓存并重新初始化。

诊断工作流

步骤 1：验证文件结构

检查内容：

• 所有必需的文件是否存在
• 是否没有 0 字节的文件
• 正确的目录层级

步骤 2：验证文件内容

步骤 3：清除缓存并重新初始化

步骤 4：检查 Terraform 版本

示例 variables.tf：

variable "rg_name" {
  description = "Resource group name"
  type        = string
}

variable "location" {
  description = "Azure region"
  type        = string
}

示例 outputs.tf

output "resource_id" {
  description = "ID of the created resource"
  value       = azurerm_resource.name.id
}

示例模块调用在 root/main.tf

module "example" {
  source   = "./modules/module_name"
  rg_name  = "my-rg"
  location = "eastus"
}

# Reference module output
resource "other_resource" "example" {
  dependency_id = module.example.resource_id
}

常见错误需避免

❌ 不要

• 编辑文件但未保存（在 VSCode 中使用 Ctrl + S）
• 在模块更改后忘记运行 terraform init
• 使用未在 outputs.tf 中定义的模块输出
• 传递未在 variables.tf 中定义的变量

✅ 要做

• 始终确认文件已正确保存（检查文件大小）
• 在模块修改后清除 .terraform 缓存
• 运行 terraform fmt 进行代码格式化
• 运行 terraform validate 及早捕获错误
• 保持模块接口（变量 / 输出）稳定

快速参考命令

当所有其他方法都失败时

1. 重新开始

2. 逐个验证每个模块