必须安装 hashicorp 官方 terraform 插件，配置 formatonsave、确保 terraform init 完成、项目路径为英文且工作区包含所有 .tf 文件，否则补全、校验、跳转等功能失效。
VSCode 装哪个插件才能正确识别 .tf 文件
必须装 Terraform 官方插件（作者是 HashiCorp），不是“HCL”或“Terraform Syntax Highlighting”这类第三方替代品。后者只做基础高亮，不提供 validate、format、变量跳转、模块补全等核心能力。
常见错误现象：.tf 文件打开后没有缩进、无参数提示、terraform plan 报错但 VSCode 不标红线、module 块里路径点不进去。
- 在扩展商店搜 “
Terraform”，认准发布者是HashiCorp - 安装后重启 VSCode，别跳过这步——插件初始化依赖语言服务器启动
- 确认状态栏右下角显示 “
HCL” 且旁边有 Terraform 图标，不是 “Plain Text” 或 “HCL (unofficial)”
为什么 terraform fmt 在 VSCode 里不自动生效
VSCode 默认不绑定 terraform fmt 到保存动作，需要手动配置格式化工具链。而且它依赖本地已安装的 terraform CLI，不是插件自带。
使用场景：多人协作时统一代码风格、CI 拒绝未格式化提交、避免因空格/换行差异引发 diff 冲突。
- 确保系统 PATH 中能执行
terraform version（Mac/Linux 检查$PATH，Windows 检查环境变量） - 在工作区根目录加
.vscode/settings.json，写入：{ "editor.formatOnSave": true, "terraform.languageServer.enabled": true, "terraform.path": "terraform" } -
"terraform.path"值设为"terraform"即可，不要写绝对路径——除非你用的是非标准安装位置（如/opt/terraform）
补全失效、变量跳转失败的三个硬性前提
Terraform 插件的智能补全和导航不是“开箱即用”，它依赖项目结构、CLI 版本和配置文件存在状态。缺一不可。
常见错误现象：输入 aws_instance. 后没属性提示；点击 var.name 无法跳转到 variables.tf；module 的 source 路径悬停无文档。
- 项目根目录必须有
terraform { required_version = ">= 1.0" }块（哪怕只是占位），否则语言服务器拒绝加载 - 运行过至少一次
terraform init，生成.terraform/目录——插件靠它读取 provider schema 和 module 结构 - 所有
.tf文件需在同一个 VSCode 工作区打开，跨窗口或子目录未纳入工作区会导致补全断连
Windows 上中文路径导致插件崩溃怎么办
这是 Terraform 语言服务器（terraform-ls）在 Windows 下解析路径时的已知问题：遇到含中文字符的父目录名，会直接退出，VSCode 状态栏显示 “HCL language server crashed”。
性能影响：崩溃后补全、校验、跳转全部失效，且每 30 秒重试一次，拖慢编辑器响应。
- 把整个 Terraform 项目移到纯英文路径下，例如
C:/code/my-infra/，而非C:/用户/张三/桌面/infra/ - 不要尝试改
settings.json里的terraform.path来绕过——问题出在工作区路径，不是 CLI 路径 - 如果必须用中文路径，暂时禁用自动格式化和实时校验，靠命令行
terraform validate和fmt手动兜底
terraform init 状态、CLI 可达性、路径编码、工作区范围四个条件强耦合。任何一个卡住，都会表现为“好像没起作用”。
