依赖锁定文件

OpenTofu 配置可能引用两种来自其自身代码库外部的不同类型的外部依赖项

提供程序，它们是 OpenTofu 的插件，通过扩展它来支持与各种外部系统交互。
模块，它们允许将 OpenTofu 配置结构组（以 OpenTofu 语言编写）分解成可重用的抽象。

这两种依赖项类型都可以独立于 OpenTofu 本身以及依赖它们的配置发布和更新。因此，OpenTofu 必须确定这些依赖项的哪些版本可能与当前配置兼容，以及当前选择使用哪些版本。

版本约束在配置本身中确定哪些版本的依赖项是潜在的兼容项，但在选择每个依赖项的特定版本后，OpenTofu 会记住它做出的决定，并将其记录在依赖锁定文件中，以便它（默认情况下）在将来再次做出相同的决定。

目前，依赖锁定文件仅跟踪提供程序依赖项。OpenTofu 不会记住远程模块的版本选择，因此 OpenTofu 将始终选择满足指定版本约束的最新可用模块版本。您可以使用精确版本约束来确保 OpenTofu 将始终选择相同的模块版本。

锁定文件位置

依赖锁定文件是属于整个配置的文件，而不是属于配置中的每个单独模块。因此，当您运行 OpenTofu 时，OpenTofu 会在您的当前工作目录中创建它并期望找到它，该目录也包含配置根模块的 .tf 或 .tofu 文件。

锁定文件始终命名为 .terraform.lock.hcl，此名称旨在表明它是 OpenTofu 在工作目录的 .terraform 子目录中缓存的各种项目的锁定文件。

每次运行 tofu init 命令时，OpenTofu 都会自动创建或更新依赖锁定文件。您应该将此文件包含在您的版本控制存储库中，以便您可以通过代码审查来讨论对外部依赖项的潜在更改，就像您讨论对配置本身的潜在更改一样。

依赖锁定文件使用与主 OpenTofu 语言相同的低级语法，但依赖锁定文件本身不是 OpenTofu 语言配置文件。它以 .hcl 而不是 .tf 或 .tofu 为后缀命名，以表明这种区别。

依赖安装行为

当 tofu init 正在安装配置所需的所有提供程序时，OpenTofu 会同时考虑配置中的版本约束和锁定文件中记录的版本选择。

如果特定提供程序没有现有的记录选择，OpenTofu 将选择与给定版本约束匹配的最新可用版本，然后更新锁定文件以包含该选择。

如果特定提供程序已经在锁定文件中记录了选择，即使有更新的版本可用，OpenTofu 也会始终重新选择该版本进行安装。您可以通过在运行 tofu init 时添加 -upgrade 选项来覆盖此行为，在这种情况下，OpenTofu 将忽略现有的选择，并再次选择与版本约束匹配的最新可用版本。

如果特定 tofu init 调用对锁定文件进行了更改，OpenTofu 将在输出中提及这一点

代码块
OpenTofu has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

当您看到此消息时，您可以使用您的版本控制系统来审查 OpenTofu 在文件中提出的更改，如果它们代表您有意进行的更改，则可以通过团队通常的代码审查流程发送更改。

校验和验证

OpenTofu 还将验证它安装的每个包是否至少与它之前在锁定文件中记录的校验和之一匹配（如果有），如果没有任何校验和匹配，则返回错误

代码块
Error: Failed to install provider

Error while installing hashicorp/azurerm v2.1.0: the current package for
registry.opentofu.org/hashicorp/azurerm 2.1.0 doesn't match any of the
checksums previously recorded in the dependency lock file.

此校验和验证旨在表示一种首次使用信任 方法。当您首次添加新提供程序时，您可以通过您选择的任何方式或相关法规要求的任何方式对其进行验证，然后信任 OpenTofu 会在将来运行 tofu init 时遇到相同提供程序版本的非匹配包时引发错误。

"首次使用信任" 模型有两个特殊注意事项

如果您从提供带有加密签名的校验和的源注册表安装提供程序，那么只要一个校验和匹配，OpenTofu 就会将所有已签名的校验和视为有效。因此，锁定文件将包含您为当前平台安装的软件包的校验和以及可能适用于其他平台的任何其他软件包的校验和。

在这种情况下，tofu init 的输出将包含签署校验和的密钥的指纹，并显示类似 (signed, key ID 0C0AF313E5FD9F80) 的消息。在提交包含已签名校验和的锁定文件之前，您可能希望确认您信任给定密钥的持有者，或者检索并验证给定提供程序版本的完整可用软件包集。
如果您第一次使用替代安装方法（例如文件系统或网络镜像）安装提供程序，OpenTofu 将无法验证除运行 tofu init 的平台之外的任何其他平台的校验和，因此它不会记录其他平台的校验和，因此该配置将无法在任何其他平台上使用。

要避免此问题，您可以使用tofu providers lock 命令在锁定文件中预填充各种不同平台的校验和，这将允许将来对 tofu init 的调用验证您选择的镜像中可用的软件包是否与提供程序源注册表中的官方软件包匹配。

了解锁定文件更改

由于依赖项锁定文件主要由 OpenTofu 本身自动维护，而不是由您或您的团队手动更新，因此您的版本控制系统可能会显示该文件已更改。

OpenTofu 可能会对您的锁定文件进行几种不同类型的更改，您可能需要了解这些更改才能审查建议的更改。以下部分将描述这些常见情况。

依赖于新的提供程序

如果您在配置中任何模块的提供程序要求中添加新条目，或者如果您添加包含新的提供程序依赖项本身的外部模块，tofu init 将通过选择满足配置中所有版本约束的该提供程序的最新版本来响应，并且它会将其决策记录为依赖项锁定文件中的一个新的 provider 块。

代码块
--- .terraform.lock.hcl	2020-10-07 16:12:07.539570634 -0700
+++ .terraform.lock.hcl	2020-10-07 16:12:15.267487237 -0700
@@ -6,6 +6,26 @@
   ]
 }

+provider "registry.opentofu.org/hashicorp/azurerm" {
+  version     = "2.30.0"
+  constraints = "~> 2.12"
+  hashes = [
+    "h1:FJwsuowaG5CIdZ0WQyFZH9r6kIJeRKts9+GcRsTz1+Y=",
+    "h1:c/ntSXrDYM1mUir2KufijYebPcwKqS9CRGd3duDSGfY=",
+    "h1:yre4Ph76g9H84MbuhZ2z5MuldjSA4FsrX6538O7PCcY=",
+    "zh:04f0a50bb2ba92f3bea6f0a9e549ace5a4c13ef0cbb6975494cac0ef7d4acb43",
+    "zh:2082e12548ebcdd6fd73580e83f626ed4ed13f8cdfd51205d8696ffe54f30734",
+    "zh:246bcc449e9a92679fb30f3c0a77f05513886565e2dcc66b16c4486f51533064",
+    "zh:24de3930625ac9014594d79bfa42d600eca65e9022b9668b54bfd0d924e21d14",
+    "zh:2a22893a576ff6f268d9bf81cf4a56406f7ba79f77826f6df51ee787f6d2840a",
+    "zh:2b27485e19c2aaa9f15f29c4cff46154a9720647610171e30fc6c18ddc42ec28",
+    "zh:435f24ce1fb2b63f7f02aa3c84ac29c5757cd29ec4d297ed0618423387fe7bd4",
+    "zh:7d99725923de5240ff8b34b5510569aa4ebdc0bdb27b7bac2aa911a8037a3893",
+    "zh:7e3b5d0af3b7411dd9dc65ec9ab6caee8c191aee0fa7f20fc4f51716e67f50c0",
+    "zh:da0af4552bef5a29b88f6a0718253f3bf71ce471c959816eb7602b0dadb469ca",
+  ]
+}
+
 provider "registry.opentofu.org/newrelic/newrelic" {
   version     = "2.1.2"
   constraints = "~> 2.1.1"

新的锁定文件条目记录了多条信息

version：根据配置中的版本约束，OpenTofu 选择的确切版本。
constraints：OpenTofu 在做出此选择时考虑的所有版本约束。（OpenTofu 实际上并没有使用此信息来做出安装决策，但包含它是为了帮助向人类读者解释之前的决策是如何做出的。）
hashes：许多校验和都被认为对在不同平台上实现此提供程序的选定版本的软件包有效。这些哈希的含义在下面新的提供程序软件包校验和中有更多解释。

现有提供程序的新版本

如果您运行 tofu init -upgrade 以要求 OpenTofu 考虑仍然匹配已配置版本约束的较新提供程序版本，那么 OpenTofu 可能会为提供程序选择较新版本并更新其现有的 provider 块以反映该更改。

代码块
--- .terraform.lock.hcl	2020-10-07 16:44:25.819579509 -0700
+++ .terraform.lock.hcl	2020-10-07 16:43:42.785665945 -0700
@@ -7,22 +7,22 @@
 }

 provider "registry.opentofu.org/hashicorp/azurerm" {
-  version     = "2.1.0"
-  constraints = "~> 2.1.0"
+  version     = "2.0.0"
+  constraints = "2.0.0"
   hashes      = [
-    "h1:EOJImaEaVThWasdqnJjfYc6/P8N/MRAq1J7avx5ZbV4=",
-    "zh:0015b491cf9151235e57e35ea6b89381098e61bd923f56dffc86026d58748880",
-    "zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",
-    "zh:57bac885b108c91ade4a41590062309c832c9ab6bf6a68046161636fcaef1499",
-    "zh:5810d48f574c0e363c969b3f45276369c8f0a35b34d6202fdfceb7b85b3ac597",
-    "zh:5c6e37a44462b8662cf9bdd29ce30523712a45c27c5d4711738705be0785db41",
-    "zh:64548940a3387aa3a752e709ee9eb9982fa820fe60eb60e5f212cc1d2c58549e",
-    "zh:7f46749163da17330bbb5293dc825333c86304baa0a7c6256650ac536b4567c8",
-    "zh:8f8970f2df75ac43ffdd112055ee069d8bd1030f7eb4367cc4cf494a1fa802c3",
-    "zh:9ad693d00dc5d7d455d06faba70e716bce727c6706f7293288e87fd7956b8fe0",
-    "zh:b6e3cb55e6aec62b47edd0d2bd5e14bd6a2bcfdac65930a6e9e819934734c57b",
-    "zh:d6a3f3b9b05c28ecf3919e9e7afa185805a6d7442fc4b3eedba749c2731d1f0e",
-    "zh:d81fb624a357c57c7ea457ce543d865b39b12f26c2edd58a2f7cd43326c91010",
+    "h1:bigGXBoRbp7dv79bEEn+aaju8575qEXHQ57XHVPJeB8=",
+    "zh:09c603c8904ca4a5bc19e82335afbc2837dcc4bee81e395f9daccef2f2cba1c8",
+    "zh:194a919d4836d6c6d4ce598d0c66cce00ddc0d0b5c40d01bb32789964d818b42",
+    "zh:1f269627df4e266c4e0ef9ee2486534caa3c8bea91a201feda4bca525005aa0a",
+    "zh:2bae3071bd5f8e553355c4b3a547d6efe1774a828142b762e9a4e85f79be7f63",
+    "zh:6c98dfa5c3468e8d02e2b3af7c4a8a14a5d469ce5a642909643b413a17ca338b",
+    "zh:7af78f61666fd45fbf428161c061ea2623162d601b79dc71d6a5158756853ffa",
+    "zh:883c2df86ae9ba2a5c167cf5c2c7deca0239171a224d6d335f0fd6dd9c283830",
+    "zh:a2028379078577d8ff5ecfca6e8a8b25a25ffb1686de0ee52a7fe8011783488b",
+    "zh:abe6ef399552fd3861a454a839cd978c1d15735658fdc00f9054435aff0f4620",
+    "zh:c30b1bf14077913c3cdf34979b1434dbb1353cb5995eb3956b191c50538b64a9",
+    "zh:ca64ae2ad9793e5631e3b0b9327f7cb22cb5d8e9de57be7d85821791b1d5a375",
+    "zh:fffe56904a38109bb8d613b02808a177c3ddfac19f03b3aac799281fea38f475",
   ]
 }

选择新的提供程序版本的主要影响是更改 provider 块中 version 的值。如果升级伴随着对已配置版本约束的更改，OpenTofu 也会在 constraints 值中记录该更改。

由于每个版本都有自己的一组分发包，因此切换到新版本也往往会替换 hashes 中的所有值，以反映新版本的包的校验和。

新的提供程序软件包校验和

您在 provider 块中可能会看到的另一个细微变化是添加了以前未记录的新校验和，即使 provider 块中的其他内容没有更改。

代码块
--- .terraform.lock.hcl	2020-10-07 17:24:23.397892140 -0700
+++ .terraform.lock.hcl	2020-10-07 17:24:57.423130253 -0700
@@ -10,6 +10,7 @@
   version     = "2.1.0"
   constraints = "~> 2.1.0"
   hashes = [
+    "h1:1xvaS5D8B8t6J6XmXxX8spo97tAzjhacjedFX1B47Fk=",
     "h1:EOJImaEaVThWasdqnJjfYc6/P8N/MRAq1J7avx5ZbV4=",
     "zh:0015b491cf9151235e57e35ea6b89381098e61bd923f56dffc86026d58748880",
     "zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",

将新的校验和添加到 hashes 值中表示 OpenTofu 正在逐渐在不同的哈希方案之间进行转换。这些值上的 h1: 和 zh: 前缀表示不同的哈希方案，每个方案都表示使用不同的算法计算校验和。如果我们了解到现有方案的局限性，或者如果新方案提供了一些相当大的额外好处，我们可能会偶尔引入新的哈希方案。

目前支持的两种哈希方案是

zh:：“zip hash”的助记符，这是一种旧的哈希格式，它是 OpenTofu 提供程序注册表协议的一部分，因此用于您直接从源注册表安装的提供程序。

此哈希方案捕获源注册表中索引的每个官方 .zip 软件包的 SHA256 哈希。这是一种有效的方案，用于验证从注册表安装的官方发布软件包，但它不适用于验证来自其他提供程序安装方法（例如使用解压缩目录布局的文件系统镜像）的软件包。
h1:：“哈希方案 1”的助记符，这是当前首选的哈希方案。

哈希方案 1 也是 SHA256 哈希，但它是根据提供程序分发包的内容计算的，而不是根据它所包含的 .zip 存档计算的。因此，此方案具有以下优势：它可以针对官方 .zip 文件、具有相同内容的解压缩目录或包含相同文件但元数据或压缩方案可能不同的重新压缩 .zip 文件进行计算。

由于 zh: 方案的范围有限，因此 OpenTofu 会在了解到它们时主动添加相应的 h1: 校验和，这就是上面显示的示例更改中添加第二个 h1: 校验和的原因。

只有当哈希是从也与现有哈希之一匹配的软件包计算出来的，OpenTofu 才会将新的哈希添加到现有提供程序中。在上面的示例中，OpenTofu 为与生成原始 h1: 校验和不同的平台安装了 hashicorp/azurerm 软件包，但能够根据之前记录的 zh: 校验和之一与之匹配。在确认 zh: 校验和匹配后，OpenTofu 然后记录了相应的 h1: 校验和，以便逐渐从旧方案迁移到新方案。

在第一次安装特定提供程序时（其中没有为其提供现有的 provider 块），OpenTofu 将使用提供程序开发人员的加密签名涵盖的任何校验和预填充 hashes 值，这通常涵盖该提供程序版本在所有受支持平台上提供的所有可用软件包。但是，由于提供程序注册表协议仍然使用 zh: 方案，因此初始集将主要由使用该方案的哈希组成，然后 OpenTofu 会在您在不同平台上安装软件包时主动升级这些哈希。

如果您希望避免在您在新的目标平台上使用配置时持续添加新的 h1: 哈希，或者如果您从镜像安装提供程序，因此无法提供官方签名的校验和，您可以要求 OpenTofu 使用tofu providers lock 命令预填充一组选定平台的哈希。

代码块
tofu providers lock \
  -platform=linux_arm64 \
  -platform=linux_amd64 \
  -platform=darwin_amd64 \
  -platform=windows_amd64

上述命令将下载并验证所有必需提供程序在所有四个给定平台上的官方软件包，然后在锁定文件中记录每个软件包的 zh: 和 h1: 校验和，从而避免 OpenTofu 仅在稍后时间了解 h1: 等效项的情况。有关此命令的更多信息，请参阅 tofu providers lock 文档。

不再需要的提供程序

要确定是否存在对给定提供程序的依赖关系，OpenTofu 使用两个真相来源：配置本身和状态。如果您从配置和状态中删除对特定提供程序的最后一个依赖项，那么 tofu init 将删除该提供程序的任何现有锁定文件条目。

代码块
--- .terraform.lock.hcl	2020-10-07 16:12:07.539570634 -0700
+++ .terraform.lock.hcl	2020-10-07 16:12:15.267487237 -0700
@@ -6,26 +6,6 @@
   ]
 }

-provider "registry.opentofu.org/hashicorp/azurerm" {
-  version     = "2.30.0"
-  constraints = "~> 2.12"
-  hashes = [
-    "h1:FJwsuowaG5CIdZ0WQyFZH9r6kIJeRKts9+GcRsTz1+Y=",
-    "h1:c/ntSXrDYM1mUir2KufijYebPcwKqS9CRGd3duDSGfY=",
-    "h1:yre4Ph76g9H84MbuhZ2z5MuldjSA4FsrX6538O7PCcY=",
-    "zh:04f0a50bb2ba92f3bea6f0a9e549ace5a4c13ef0cbb6975494cac0ef7d4acb43",
-    "zh:2082e12548ebcdd6fd73580e83f626ed4ed13f8cdfd51205d8696ffe54f30734",
-    "zh:246bcc449e9a92679fb30f3c0a77f05513886565e2dcc66b16c4486f51533064",
-    "zh:24de3930625ac9014594d79bfa42d600eca65e9022b9668b54bfd0d924e21d14",
-    "zh:2a22893a576ff6f268d9bf81cf4a56406f7ba79f77826f6df51ee787f6d2840a",
-    "zh:2b27485e19c2aaa9f15f29c4cff46154a9720647610171e30fc6c18ddc42ec28",
-    "zh:435f24ce1fb2b63f7f02aa3c84ac29c5757cd29ec4d297ed0618423387fe7bd4",
-    "zh:7d99725923de5240ff8b34b5510569aa4ebdc0bdb27b7bac2aa911a8037a3893",
-    "zh:7e3b5d0af3b7411dd9dc65ec9ab6caee8c191aee0fa7f20fc4f51716e67f50c0",
-    "zh:da0af4552bef5a29b88f6a0718253f3bf71ce471c959816eb7602b0dadb469ca",
-  ]
-}
-
 provider "registry.opentofu.org/newrelic/newrelic" {
   version     = "2.1.2"
   constraints = "~> 2.1.1"

如果您在以后的日期添加了对同一提供程序的新要求并再次运行 tofu init，OpenTofu 将将其视为一个全新的提供程序，因此不会必要地选择之前选择的相同版本，并且将无法验证校验和是否保持不变。

依赖锁定文件

锁定文件位置​

依赖安装行为​

校验和验证​

了解锁定文件更改​

依赖于新的提供程序​

现有提供程序的新版本​

新的提供程序软件包校验和​

不再需要的提供程序​