devenv 中 Terraform 开发环境配置指南:enable、version 与 LSP 完整解析
devenv 中 Terraform 开发环境配置指南:enable、version 与 LSP 完整解析
本指南以 devenv 项目中的 Terraform 语言模块(languages/terraform 文档 与 terraform.nix 模块实现)为核心,系统讲解如何在 Nix 驱动的可复现开发环境中启用 Terraform 工具链、锁定指定版本、接入 Terraform Language Server,并自动获得 terraform fmt / terraform validate 等 Git 钩子与安全扫描工具 tfsec。读完本文,你将能独立编写一份生产可用的 Terraform devenv 配置。
模块概览:一份配置,四条能力
在 devenv 中,Terraform 支持由 languages.terraform 这一组 Nix 选项提供。从 terraform.nix 的源码结构看,该模块共暴露 4 个可配置选项:
| 选项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
languages.terraform.enable |
boolean | false |
是否启用 Terraform 开发工具 |
languages.terraform.package |
package | pkgs.terraform |
使用的 Terraform 包 |
languages.terraform.version |
null 或 string | null |
指定 Terraform 版本,自动覆盖 package |
languages.terraform.lsp.enable |
boolean | true |
是否启用 Terraform Language Server |
languages.terraform.lsp.package |
package | pkgs.terraform-ls |
使用的语言服务器包 |
启用模块后,根据 terraform.nix 的 config 部分,系统会自动为你注入四类能力:
- Terraform CLI:
cfg.package(默认pkgs.terraform)被加入环境的packages; - terraform-ls 语言服务器:当
lsp.enable为真时,cfg.lsp.package(默认pkgs.terraform-ls)被加入packages; - 安全扫描工具 tfsec:
pkgs.tfsec无条件加入packages; - Git 钩子:
terraform-format与terraform-validate两个 git-hooks 钩子被注册,且默认使用与模块一致的cfg.package。
也就是说,只需要一行 languages.terraform.enable = true,即可获得 CLI、LSP、安全扫描与提交前格式化/校验的一整套 Terraform 开发体验。
最小可用配置:一行启用全部工具链
在你的项目根目录创建 devenv.nix,写入:
{ pkgs, ... }:
{
languages.terraform.enable = true;
}
devenv up 或 devenv shell 之后,环境中将包含 terraform、tfsec 与 terraform-ls 三个可执行程序。同时 devenv 会注册两个 Git 预提交钩子(在 devenv.nix 中通过 git-hooks.hooks 自动声明,源码见 terraform.nix):
terraform-format:调用terraform fmt -check检查格式(配置不合规时提交会被拒绝);terraform-validate:调用terraform validate做静态校验,确保配置语法与引用有效。
如果你只想保留 CLI 而关闭语言服务器,可以显式覆盖默认值:
{ pkgs, ... }:
{
languages.terraform = {
enable = true;
lsp.enable = false;
};
}
注意:languages.terraform.lsp.enable 与模块级 enable 不同,它在 terraform.nix 中的默认值是 true,即语言服务器默认随模块一起启用,关闭需要显式指定。
锁定版本:用 version 选项固定 Terraform 发行版
Terraform 版本迭代较快,跨版本行为差异(如 HCL 语法、provider 语义)容易导致"本地能跑、CI 跑不了"。devenv 为此提供了 languages.terraform.version:
{ pkgs, ... }:
{
languages.terraform = {
enable = true;
version = "1.8.4";
};
}
设置 version 后,模块会自动把 languages.terraform.package 覆盖为对应版本的 Terraform。其底层实现位于 terraform.nix:
languages.terraform.package = lib.mkIf (cfg.version != null) (
let
terraform-pkgs = nixpkgs-terraform.packages.${pkgs.stdenv.system};
in
terraform-pkgs."terraform-${cfg.version}" or terraform-pkgs.${cfg.version}
or (throw "Unsupported Terraform version, ...")
);
这里的关键机制有两点:
- 版本来源:devenv 通过
config.lib.getInput拉取github:stackbuilders/nixpkgs-terraform作为 flake input(见 terraform.nix),该仓库维护了一份社区维护的、按版本发布的 Terraform 包集合。如果项目使用devenv.yaml声明 inputs,也需要同步声明:
# devenv.yaml
inputs:
nixpkgs-terraform:
url: github:stackbuilders/nixpkgs-terraform
- 匹配逻辑:模块优先查找
terraform-${version}属性,找不到时再尝试直接以版本号命名的属性;两者都不存在则抛出错误,提示升级 input 或查阅 nixpkgs-terraform 的版本清单。这意味着版本支持范围由锁定的devenv.lock中nixpkgs-terraforminput 决定——写入版本后应执行devenv update刷新 lockfile,确保 input 中确实包含该版本。
与
package的关系:version与package是互斥思路——指定version时package会被自动覆盖,因此无需(也不应)同时手写package;若你使用的是 nixpkgs 直接打包的terraform(如package = pkgs.terraform),则保持version = null即可。
自定义包:替换 CLI 与语言服务器
除了版本锁定,模块也允许完全自定义所用包,适用于使用内部 fork、预编译二进制或厂商分发版本等场景:
{ pkgs, ... }:
{
languages.terraform = {
enable = true;
package = pkgs.terraform_1; # 例如 nixpkgs 中具体的 terraform 版本属性
lsp.package = pkgs.terraform-ls;
};
}
package 的类型是 lib.types.package(见 terraform.nix),默认值为 pkgs.terraform;lsp.package 的类型同为 package,默认值为 pkgs.terraform-ls。自定义时需确保替换的包与 terraform fmt、terraform validate 钩子的 CLI 兼容——钩子默认沿用了 cfg.package(见 terraform.nix),所以换包会同时影响钩子行为。
此外,若勾子默认包不符合需求,还可以单独覆盖钩子的包,例如:
{ pkgs, ... }:
{
languages.terraform.enable = true;
git-hooks.hooks.terraform-format.package = pkgs.terraform_1;
git-hooks.hooks.terraform-validate.package = pkgs.terraform_1;
}
与仓库示例/测试的印证
仓库在 examples/terraform 中给出了一个可直接借鉴的最小示例,同时演示了 enable 与 version 的组合用法:
{ pkgs, ... }:
{
languages.terraform = {
enable = true;
version = "1.8.4";
};
}
对应的 devenv.yaml 声明了模块所需的版本仓库 input:
inputs:
nixpkgs-terraform:
url: github:stackbuilders/nixpkgs-terraform
这恰好印证了前文提到的"version 依赖 nixpkgs-terraform input"这一前提。同时,opentofu.nix 也注册了同名钩子,说明 terraform-format/terraform-validate 钩子命名在 Terraform 生态(包括 OpenTofu 兼容实现)中是统一的,便于工具链之间的迁移与复用。
常见问题与使用建议
Q1:设置了 version 但提示 unsupported version?
说明当前锁定的 nixpkgs-terraform input 中不存在该版本。执行 devenv update(或更新对应 input)后再试,必要时查阅 nixpkgs-terraform 的版本清单确认可用版本号。
Q2:只想做格式/校验,不想装 LSP?
设置 languages.terraform.lsp.enable = false 即可,钩子与 CLI 不受影响;反之只想要 IDE 支持而不做钩子检查,则覆盖 git-hooks.hooks.terraform-validate.enable = false 等钩子开关。
Q3:如何在编辑器中使用 terraform-ls?
模块默认安装 terraform-ls(二进制加入 PATH),主流编辑器(如 VSCode 的 HashiCorp Terraform 扩展、Neovim 的 lspconfig)会自动发现 PATH 中的 terraform-ls 并按 LSP 协议连接,无需额外配置绝对路径。
Q4:钩子与 CLI 版本不一致怎么办?
钩子默认绑定 languages.terraform.package(源码见 terraform.nix),因此正常情况下不会出现版本漂移;若确需单独指定,可按上文覆盖 git-hooks.hooks.terraform-format.package。
小结
devenv 的 languages.terraform 模块以极少的配置项覆盖了 Terraform 开发的全链路:一行 enable = true 即可获得 CLI、tfsec 与 terraform-ls;version 选项借助 nixpkgs-terraform 实现可复现的版本锁定;package / lsp.package 支持深度自定义;而 terraform-format 与 terraform-validate 钩子则把格式与校验自动带入了 Git 提交流程。所有行为都可在 src/modules/languages/terraform.nix 中溯源,适合作为团队统一 Terraform 开发环境的基准配置。