CLI 配置文件 (`.tofurc` 或 `tofu.rc`)

CLI 配置文件配置每个用户的 CLI 行为设置，这些设置适用于所有 OpenTofu 工作目录。这与您的基础设施配置是分开的。

位置

配置可以放置在一个文件中，其位置取决于主机操作系统

在 Windows 上，文件必须命名为 tofu.rc 并放置在相关用户的 %APPDATA% 目录中。此目录的物理位置取决于您的 Windows 版本和系统配置；在 PowerShell 中使用 $env:APPDATA 查找系统上的位置。出于向后兼容的目的，支持 terraform.rc。如果 terraform.rc 和 tofu.rc 文件都存在，则后者优先。
在所有其他系统上，文件必须命名为 .tofurc（注意前面的句点）并直接放置在相关用户的 home 目录中，或者命名为 tofurc 并放置在一个有效的 XDG 基础目录配置目录（如 $XDG_CONFIG_HOME/opentofu）中。出于向后兼容的目的，支持 .terraformrc。如果 .terraformrc 和 .tofurc 文件都存在，则后者优先。当使用 XDG 配置目录时，将忽略 .terraformrc 和 terraformrc。

在 Windows 上，请注意 Windows 资源管理器的默认行为是隐藏文件名扩展名。即使 Windows 资源管理器可能显示其名称仅为 tofu.rc，OpenTofu 也不会将名为 tofuc.rc.txt 的文件识别为 CLI 配置文件。使用 PowerShell 或命令提示符中的 dir 确认文件名。

OpenTofu CLI 配置文件的位置也可以使用 TF_CLI_CONFIG_FILE 环境变量指定。任何此类文件都应遵循 *.tfrc 的命名模式。

配置文件语法

配置文件使用与 .tf 和 .tofu 文件相同的HCL 语法，但具有不同的属性和块。以下示例说明了通用语法；有关每个设置含义的信息，请参见下一节

代码块
plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"

可用设置

以下设置可以在 CLI 配置文件中设置

credentials - 配置用于云后端的凭据。有关更多信息，请参见下面的凭据。
credentials_helper - 为云后端的凭据存储和检索配置外部辅助程序。有关更多信息，请参见下面的凭据辅助程序。
plugin_cache_dir — 启用插件缓存并以字符串形式指定插件缓存目录的位置。
provider_installation - 自定义 tofu init 在安装提供程序插件时使用的安装方法。有关更多信息，请参见下面的提供程序安装。

凭据

在与 OpenTofu 特定的网络服务交互时，OpenTofu 期望在 CLI 配置文件中的 credentials 块中找到 API 令牌

代码块
credentials "app.opentofu.org" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

如果您在配备 Web 浏览器的计算机上以交互方式运行 OpenTofu CLI，则可以使用 tofu login 命令获取凭据并自动将其保存到 CLI 配置中。否则，您可以手动编写 credentials 块。

如果您定期使用来自多个主机的服务，则可以有多个 credentials 块。每个 credentials 块都包含一个 token 参数，用于提供要用于该主机的 API 令牌。

注意

凭据主机名必须与模块源代码和/或后端配置中的主机名匹配。

环境变量凭据

如果您不想将 API 令牌直接存储在 CLI 配置中，则可以使用特定于主机的环境变量。环境变量名称应在域名前加上前缀 TF_TOKEN_，并将句点编码为下划线。例如，名为 TF_TOKEN_app_opentofu_org 的变量的值将在 CLI 向主机名 app.opentofu.org 发出服务请求时用作承载者授权令牌。

您必须将包含非 ASCII 字符的域名转换为其Punycode 等效项，并加上 ACE 前缀。例如，例如.com 的令牌凭据必须设置在名为 TF_TOKEN_xn--r8j3dr99h_com 的变量中。

连字符在主机名中也有效，但在变量名中通常无效，可以编码为双下划线。例如，您可以为域名 café.fr 设置令牌为 TF_TOKEN_xn--caf-dma.fr、TF_TOKEN_xn--caf-dma_fr 或 TF_TOKEN_xn____caf__dma_fr。如果多个变量解析为相同的主机名，OpenTofu 将选择操作系统变量表中最后定义的那个。

凭据助手

您可以配置一个 credentials_helper 来指示 OpenTofu 使用不同的凭据存储机制。

代码块
credentials_helper "example" {
  args = []
}

credentials_helper 是一个配置块，最多可以在 CLI 配置中出现一次。其标签（上面为 "example"）是要使用的凭据助手的名称。args 参数是可选的，允许向助手程序传递其他参数，例如，如果需要使用远程主机的地址来配置它以访问凭据。

配置的凭据助手仅用于检索尚未在上一节中描述的 credentials 块中显式配置的主机的凭据。反过来，这意味着您可以通过在 credentials_helper 块旁边编写 credentials 块来覆盖助手返回的特定主机名的凭据。

OpenTofu 在主发行版中不包含任何凭据助手。要了解如何编写和安装您自己的凭据助手以与现有的内部凭据管理系统集成，请参阅凭据助手内部指南。

凭据源优先级顺序

如上所述，在特定服务主机环境变量中找到的凭据将优先于通过 tofu login 设置的 CLI 配置中的凭据。如果两者均未设置，则将咨询任何已配置的凭据助手。

提供程序安装

安装提供程序插件的默认方法是从提供程序注册表中安装。提供程序的源注册表编码在其提供程序的源地址中，例如 registry.opentofu.org/hashicorp/aws。为了方便起见，在常见情况下，OpenTofu 允许省略 registry.opentofu.org 上提供程序的主机名部分，因此您可以编写更短的公共提供程序地址，例如 hashicorp/aws。

但是，并非总是适合直接从其源注册表下载插件。例如，由于您组织或您所在地区的防火墙限制，您运行 OpenTofu 的系统可能无法访问源注册表。

为了允许在这些情况下使用 OpenTofu 提供程序，有一些替代方案可用于使提供程序插件可供 OpenTofu 使用，我们将在以下部分中介绍这些方案。

显式安装方法配置

CLI 配置中的 provider_installation 块允许覆盖 OpenTofu 的默认安装行为，因此您可以强制 OpenTofu 对您打算使用的某些或所有提供程序使用本地镜像。

provider_installation 块的通用结构如下所示

代码块
provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}

provider_installation 块内的每个嵌套块都指定了一种安装方法。每种安装方法都可以使用 include 和 exclude 模式来指定特定安装方法可用于哪些提供程序。在上面的示例中，我们指定任何源注册表位于 example.com 的提供程序只能从 /usr/share/terraform/providers 的文件系统镜像中安装，而所有其他提供程序只能直接从其源注册表中安装。

如果为特定安装方法同时设置了 include 和 exclude，则排除模式优先。例如，包含 registry.opentofu.org/hashicorp/* 但也排除 registry.opentofu.org/hashicorp/dns 将使该安装方法应用于 hashicorp 命名空间中的所有内容，除了 hashicorp/dns。

与主配置中的提供程序源地址一样，即使使用通配符，您也可以省略通过公共 OpenTofu 注册表分发的提供程序的 registry.opentofu.org/ 前缀。例如，registry.opentofu.org/hashicorp/* 和 hashicorp/* 等效。*/* 是 registry.opentofu.org/*/* 的简写，而不是 */*/*。

以下是支持的安装方法类型

direct：直接从其源注册表请求有关提供程序的信息，并通过注册表指示的位置通过网络下载。此方法不需要其他参数。
filesystem_mirror：在本地磁盘上的目录中查找提供程序的副本。此方法需要附加参数 path 来指示要查找的目录。

OpenTofu 期望给定目录包含一个嵌套的目录结构，其中路径段一起提供有关可用提供程序的元数据。支持以下两种目录结构
- 打包布局：HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip 是从提供程序的源注册表获取的发行版 zip 文件。
- 解包布局：HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET 是一个目录，其中包含提取提供程序的发行版 zip 文件的结果。
在这两种布局中，VERSION 是一个类似于 2.0.0 的字符串，TARGET 使用类似于 darwin_amd64、linux_arm、windows_amd64 等格式指定特定目标平台。

如果您使用解包布局，OpenTofu 将尝试在安装提供程序时创建指向镜像目录的符号链接，而不是创建目录的深度副本。打包布局阻止了这种情况，因为 OpenTofu 必须在安装期间提取 zip 文件。

您可以包含多个 filesystem_mirror 块以指定多个要搜索的不同目录。
network_mirror：无论提供程序属于哪个注册表主机，都咨询特定 HTTPS 服务器以获取提供程序的副本。此方法需要附加参数 url 来指示镜像基本 URL，该 URL 应使用 https: 方案并在末尾加上尾部斜杠。

OpenTofu 期望给定的 URL 是提供程序网络镜像协议实现的基本 URL，该协议旨在使用典型的静态网站托管机制相对易于实现。

警告

不要配置您不信任的 network_mirror URL。提供程序镜像服务器需要进行 TLS 证书检查以验证身份，但具有 TLS 证书的网络镜像可能会提供修改后的上游提供程序副本，其中包含恶意内容。

OpenTofu 将尝试所有指定的方法，其包含和排除模式与给定提供程序匹配，并在所有这些方法中选择最新版本，这些方法匹配每个 OpenTofu 配置中给定的版本约束。如果您有一个特定提供程序的本地镜像，并且希望 OpenTofu 独占使用该本地镜像，则必须完全删除 direct 安装方法或使用其 exclude 参数禁用其对特定提供程序的使用。

隐式本地镜像目录

如果您的 CLI 配置根本不包含 provider_installation 块，则 OpenTofu 将生成一个隐式配置。隐式配置包含一系列 filesystem_mirror 方法，然后是 direct 方法。

OpenTofu 可以选择作为文件系统镜像的目录集取决于您运行 OpenTofu 的操作系统

Windows：%APPDATA%/terraform.d/plugins 和 %APPDATA%/HashiCorp/Terraform/plugins
Mac OS X：$HOME/.terraform.d/plugins、~/Library/Application Support/io.terraform/plugins 和 /Library/Application Support/io.terraform/plugins
Linux 和其他类 Unix 系统：$HOME/.terraform.d/plugins 和位于有效XDG 基本目录数据目录（例如 $XDG_DATA_HOME/opentofu/plugins）中的 opentofu/plugins。

如果当前工作目录中存在 terraform.d/plugins 目录，则 OpenTofu 还将包含该目录，无论您的操作系统是什么。当您将 -chdir 选项与 init 命令一起使用时，此行为会发生变化。在这种情况下，OpenTofu 在启动目录中检查 terraform.d/plugins 目录，而不是在您使用 -chdir 指定的目录中检查。

OpenTofu 将检查上述每个路径以查看其是否存在，如果存在，则将其视为文件系统镜像。因此，每个路径内的目录结构必须与显式安装方法配置中描述的 filesystem_mirror 块的两种结构之一匹配。

除了零个或多个隐含的filesystem_mirror块之外，OpenTofu还会创建一个隐含的direct块。OpenTofu将扫描所有文件系统镜像目录以查看哪些提供程序放置在其中，并自动将所有这些提供程序从隐含的direct块中排除。（此自动exclude行为仅适用于隐含的direct块；如果使用显式provider_installation，则需要自行编写所需的排除项。）

提供程序插件缓存

默认情况下，tofu init将插件下载到工作目录的子目录中，以便每个工作目录都是独立的。因此，如果您有多个使用相同提供程序的配置，则每个配置都会下载其插件的单独副本。

鉴于提供程序插件可能非常大（大约数百兆字节），因此此默认行为对于那些互联网连接缓慢或计费的用户来说可能不方便。因此，OpenTofu可以选择使用本地目录作为共享插件缓存，这允许每个不同的插件二进制文件仅下载一次。

要启用插件缓存，请在 CLI 配置文件中使用plugin_cache_dir设置。例如

代码块
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

此目录必须在 OpenTofu 缓存插件之前已存在；OpenTofu 不会自行创建该目录。

请注意，在 Windows 上，需要使用正斜杠分隔符（/）而不是常规的反斜杠（\），因为配置文件解析器认为反斜杠是转义序列的开始。

在配置文件中设置此项是持久设置的推荐方法。或者，可以使用TF_PLUGIN_CACHE_DIR环境变量在特定的 shell 会话中启用缓存或覆盖现有的缓存目录

export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"

启用插件缓存目录后，tofu init命令仍将使用配置的或隐含的安装方法来获取有关哪些插件可用的元数据，但一旦选择了合适的版本，它将首先检查所选插件是否已在缓存目录中可用。如果是，OpenTofu 将使用先前下载的副本。

如果所选插件不在缓存中，OpenTofu 将首先将其下载到缓存中，然后将其从缓存复制到当前工作目录下的正确位置。在可能的情况下，OpenTofu 将使用符号链接来避免在多个目录中存储缓存插件的单独副本。

插件缓存目录不能也是配置的或隐含的文件系统镜像目录之一，因为缓存管理逻辑在操作同一目录时与文件系统镜像逻辑冲突。

OpenTofu 本身永远不会在插件放入缓存后将其删除。随着时间的推移，随着插件的升级，缓存目录可能会增长到包含多个未使用的版本，您必须手动删除这些版本。

注意

插件缓存目录不能保证是并发安全的。提供程序安装程序在具有多个tofu init调用的环境中的行为是未定义的。

允许提供程序插件缓存破坏依赖项锁定文件

注意

仅在非常规和特殊情况下使用所述选项。除非您确定需要此选项并完全了解启用它的后果，否则请勿设置此选项。

默认情况下，OpenTofu 仅当全局缓存目录中的软件包至少与该提供程序的依赖项锁定文件中记录的校验和之一匹配时，才会使用这些软件包。这可确保 OpenTofu 始终能够在您第一次在特定配置中使用新提供程序时生成完整且正确的依赖项锁定文件条目。

但是，我们知道在某些特殊情况下，团队无法按预期使用依赖项锁定文件，因此他们不会像建议的那样将其包含在版本控制中，而是让 OpenTofu 在每次安装提供程序时重新生成它。

对于那些在运行之间不保留其版本控制系统中的依赖项锁定文件的团队，OpenTofu 允许使用额外的 CLI 配置设置，该设置告诉 OpenTofu 始终将缓存目录中的软件包视为有效，即使依赖项锁定文件中没有条目来确认它。

代码块
plugin_cache_may_break_dependency_lock_file = true

或者，您可以将环境变量TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE设置为除空字符串或0之外的任何值，这等效于上述设置。

设置此选项会授予 OpenTofu CLI 权限，如果这允许 OpenTofu 使用缓存来安装该提供程序，则为提供程序创建不完整的依赖项锁定文件条目。在这种情况下，依赖项锁定文件将对当前系统有效，但可能不适用于具有不同操作系统或 CPU 架构的其他计算机，因为它仅包含全局缓存中软件包的校验和。

我们建议大多数用户不设置此选项，在这种情况下，OpenTofu 将始终在您第一次使用特定配置使用提供程序时从上游安装提供程序，但随后可以在后续运行中重新使用缓存条目，一旦依赖项锁定文件记录了提供程序软件包的有效校验和。

注意

OpenTofu 团队打算在未来的版本中改进依赖项锁定文件机制，以便它可以在更多情况下使用。届时，此选项将被静默忽略。如果您的工作流程依赖于此选项的使用，请打开一个 GitHub 问题以共享有关您情况的详细信息，以便我们考虑如何在不破坏依赖项锁定文件的情况下支持它。

提供程序开发人员的开发覆盖

通常，OpenTofu 会验证提供程序的版本选择和校验和，以帮助确保所有操作都使用提供程序的预期版本进行，并且作者可以以受控的方式逐步升级到更新的提供程序版本。

但是，在开发提供程序时，这些版本和校验和规则会带来不便，因为我们通常希望针对尚未关联版本号且未在提供程序注册表中列出官方校验和集的提供程序的开发版本尝试测试配置。

为了方便提供程序开发，OpenTofu 在provider_installation块中支持一个特殊的附加块dev_overrides。此块的内容有效地覆盖了所有其他配置的安装方法，因此此类块必须始终按顺序首先出现

代码块
provider_installation {

  # Use /home/developer/tmp/terraform-null as an overridden package directory
  # for the hashicorp/null provider. This disables the version and checksum
  # verifications for this provider and forces OpenTofu to look for the
  # null provider plugin in the given directory.
  dev_overrides {
    "hashicorp/null" = "/home/developer/tmp/terraform-null"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, OpenTofu will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

在启用开发覆盖的情况下，tofu init命令仍将尝试选择合适的已发布提供程序版本进行安装并在依赖项锁定文件中记录以供将来使用，但其他命令（如tofu apply）将忽略锁定文件中hashicorp/null的条目，并将改用给定的目录。一旦您的新更改包含在提供程序的已发布版本中，您可以使用tofu init -upgrade在依赖项锁定文件中选择新版本并删除您的开发覆盖。

特定提供程序的覆盖路径应类似于分发提供程序时.zip文件中包含的目录。至少包括一个名为terraform-provider-null前缀的可执行文件，其中null是提供程序类型。如果您的提供程序在其分发包中使用其他文件，则也可以将这些文件复制到覆盖目录中。

您可能希望仅在您积极参与提供程序开发的 shell 会话中启用开发覆盖。如果是这样，您可以在开发目录中编写一个包含上述内容的本地 CLI 配置文件，例如名为dev.tfrc，然后使用TF_CLI_CONFIG_FILE环境变量指示 OpenTofu 使用该本地化的 CLI 配置而不是默认配置

export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc

开发覆盖不适用于一般用途，作为一种让 OpenTofu 在本地文件系统上查找提供程序的方法。如果您希望将已发布的提供程序的副本放在本地文件系统中，请参阅隐含本地镜像目录或显式安装方法配置。

此开发覆盖机制旨在作为一种务实的方案，以实现更流畅的提供程序开发。其行为方式、配置方法以及与依赖项锁定文件交互的方式的详细信息都可能在未来的 OpenTofu 版本中发生变化，包括可能的重大更改。因此，我们建议仅在提供程序开发工作期间临时使用开发覆盖。

CLI 配置文件 (.tofurc 或 tofu.rc)

位置​

配置文件语法​

可用设置​

凭据​

环境变量凭据​

凭据助手​

凭据源优先级顺序​

提供程序安装​

显式安装方法配置​

隐式本地镜像目录​

提供程序插件缓存​

允许提供程序插件缓存破坏依赖项锁定文件​

提供程序开发人员的开发覆盖​