Terraform初始化安装hashicorp/aws v4.21.0失败提示路径不存在

问题现象 #

执行terraform init操作时触发以下报错：

• 提供者实例化失败：Failed to instantiate provider "registry.terraform.io/hashicorp/aws" to obtain schema: unknown provider "registry.terraform.io/hashicorp/aws"
• 提供者安装阶段报错：

安装hashicorp/aws v4.21.0版本时出错：open .terraform\providers\registry.terraform.io\hashicorp\aws\4.21.0\windows_amd64\terraform-provider-aws_v4.21.0_x5.exe: 系统找不到指定的路径。

• 初始化后端阶段完整输出：

正在安装hashicorp/aws v4.21.0...
╷
│ Error: Failed to install provider
│
│ 安装hashicorp/aws v4.21.0版本时出错：open .terraform\providers\registry.terraform.io\hashicorp\aws\4.21.0\windows_amd64\terraform-provider-aws_v4.21.0_x5.exe: 系统找不到指定的路径。

排查与解决步骤 #

按优先级从高到低操作，每步完成后重新执行terraform init验证问题是否修复：

• 清理损坏的本地缓存
  下载中断、之前初始化异常会导致.terraform目录下的提供者文件残缺，直接在项目根目录执行以下PowerShell命令删除缓存：

  Remove-Item -Recurse -Force .terraform -ErrorAction SilentlyContinue
  Remove-Item -Force .terraform.lock.hcl -ErrorAction SilentlyContinue
  

• 排查Windows路径长度限制
  Windows默认限制单条路径最大长度260字符，AWS提供者本身的安装路径层级很深，如果项目存放在多层嵌套目录下，很容易触发路径超长导致文件写入失败。
  • 临时验证：把项目文件夹移动到磁盘根目录下的短路径文件夹（比如D:\tf-aws-test），再执行初始化
  • 永久修复：以管理员身份打开PowerShell执行以下命令开启长路径支持，重启系统后生效：

    New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
    

• 排查安全软件拦截
  Windows Defender、第三方杀毒软件常会自动隔离下载的.exe格式提供者文件，导致Terraform找不到对应程序。去安全软件的隔离记录里查看是否有terraform-provider-aws_v4.21.0_x5.exe的拦截条目，将Terraform项目目录、提供者缓存目录加入白名单后重试。
• 修复网络下载异常
  官方Registry访问不稳定会导致提供者安装包下载不完整，可配置国内镜像源解决：在用户目录下找到AppData\Roaming\terraform.rc文件（不存在就新建），写入以下配置：

  provider_installation {
    network_mirror {
      url = "https://mirrors.tencent.com/terraform/"
      include = ["registry.terraform.io/*/*"]
    }
    direct {
      exclude = ["registry.terraform.io/*/*"]
    }
  }
  

• 检查目录权限
  不要把Terraform项目放在C:\Program Files等需要管理员权限才能写入的目录，可右键点击终端选择「以管理员身份运行」后重新执行初始化，排除权限不足导致的文件写入失败。

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