使用Git+SSH调用Terraform模块子目录报错求助

我之前也踩过这个坑！用Git+SSH路径引用Terraform模块的子目录时，看似简单的//分隔符，实际操作中很容易因为细节没注意到报错。咱们来理清楚正确的用法和常见问题：

正确的SSH模块源格式 #

首先放一个标准的示例，你可以对照着调整：

module "web_server" {
  source = "git@github.com:your-org/terraform-modules.git//modules/aws/web-server?ref=v1.2.0"
  
  # 这里填模块需要的变量
  instance_count = 2
  instance_type  = "t3.micro"
}

这里几个关键部分要注意：

• git@github.com:your-org/terraform-modules.git：这是你的仓库SSH地址，替换成实际的Git服务（GitHub/GitLab/Bitbucket等）地址
• //modules/aws/web-server：//是Terraform用来区分仓库根目录和子模块路径的分隔符，后面的路径必须是从仓库根目录开始的绝对路径，不能用相对路径
• ?ref=v1.2.0：这个非常重要！Terraform要求模块源必须指定明确的版本（分支、标签或提交哈希），如果漏掉这部分，大概率会报错，尤其是私有仓库

常见报错原因排查 #

1. 子目录路径错误

   • 检查路径的大小写：Git是大小写敏感的，比如Modules和modules会被认成不同路径
   • 确认路径是否从根目录开始：比如你的模块在仓库的infra/modules/network下，那就要写//infra/modules/network，不能只写//network

2. 未指定版本引用（ref）
   很多人会忽略?ref参数，Terraform在处理Git源时，如果没有明确的版本，会提示错误或者行为不稳定，一定要加上分支名、标签或者具体的提交哈希值。

3. SSH权限问题
   有时候权限不足会伪装成路径错误，你可以先在本地测试下SSH能不能正常克隆仓库：

   git clone git@github.com:your-org/terraform-modules.git
   

   如果克隆失败，先解决SSH密钥配置问题（比如把密钥添加到Git服务的账户里），再回来试Terraform。

4. 特殊字符转义
   如果你的子目录路径里有特殊字符（比如空格），需要用URL转义，比如空格换成%20，不过尽量避免在模块路径里用特殊字符，会增加不必要的麻烦。

其他Git服务的示例格式 #

• GitLab：

module "database" {
  source = "git@gitlab.com:your-team/terraform-modules.git//modules/gcp/postgres?ref=main"
}

• Bitbucket：

module "storage" {
  source = "git@bitbucket.org:your-company/terraform-modules.git//modules/azure/storage-account?ref=commit-hash-here"
}

如果还是报错，可以把具体的错误信息贴出来，这样能更精准地定位问题！

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