devenv 中 Terraform 开发环境配置指南:enable、version 与 LSP 完整解析

原创2026-09-27 09:35:291,654 阅读
文章标签:开发工具CLI

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 部分,系统会自动为你注入四类能力:

  1. Terraform CLI:cfg.package(默认 pkgs.terraform)被加入环境的 packages;
  2. terraform-ls 语言服务器:当 lsp.enable 为真时,cfg.lsp.package(默认 pkgs.terraform-ls)被加入 packages;
  3. 安全扫描工具 tfsec:pkgs.tfsec 无条件加入 packages;
  4. 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, ...")
);

这里的关键机制有两点:

  1. 版本来源: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
  1. 匹配逻辑:模块优先查找 terraform-${version} 属性,找不到时再尝试直接以版本号命名的属性;两者都不存在则抛出错误,提示升级 input 或查阅 nixpkgs-terraform 的版本清单。这意味着版本支持范围由锁定的 devenv.lock 中 nixpkgs-terraform input 决定——写入版本后应执行 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 开发环境的基准配置。

登录后查看全文
devenv