环境变量

概述

你可能有一个或多个环境变量，希望在渲染项目时确保它们被设置。例如，你可能会使用环境变量来：

  1. 提供下载数据的服务器URL。
  2. 设置代理服务器的地址（例如 HTTP_PROXY）。
  3. 提供访问远程服务器的凭证（注意，下面我们将介绍使用存储在环境变量中的凭证的最佳实践）。
  4. 调整可执行代码的行为（例如 OMP_NUM_THREADS、ARROW_IO_THREADS 等）。
  5. 为语言解释器提供选项（例如 PYTHONINSPECT 或 TZDIR）。
  6. 确定使用哪个版本的 Python 和 R（例如 QUARTO_PYTHON、QUARTO_R、PY_PYTHON 或 RETICULATE_PYTHON）。

Quarto 项目可以定义一组标准环境变量，并根据 活动项目配置文件 来决定定义哪些环境变量。还可以使用仅在本地系统上定义且不提交到版本控制的环境变量。

环境文件

如果你在项目根目录下包含一个 _environment 文件，与 _quarto.yml 文件一起，文件中定义的值将在读取项目配置时被读取并设置到环境中。例如：

_environment
HTTP_PROXY="https://proxy.example.com/"
OMP_NUM_THREADS=4

这些环境变量将在 Quarto 的执行上下文以及子进程（例如 Jupyter 内核）中可用。

请注意，环境文件中定义的变量 不会优先于 外部环境中已存在的定义。相反，它们提供了默认值，当外部环境中没有同名变量时将应用这些默认值。

你可以在环境文件中包含注释，以及引用其他环境变量。例如：

_environment
# 数据库服务器
DATABASE_SERVER=https://db.example.com
DATABASE_API=${DATABASE_SERVER}/api

当引用另一个环境变量时，它必须也在同一文件中定义，或者已经存在于外部环境中。有关环境文件语法的更多详细信息，请参阅完整的环境变量 解析规则。

配置文件环境

如果你使用 项目配置文件 来适应不同场景的项目，你可以创建一个自定义环境文件，该文件将与配置文件一起激活。例如，如果你有一个名为 production 的配置文件，那么 _environment-production 中定义的变量将被读取并应用。

在这里，我们将 OMP_NUM_THREADS 环境变量定制为在生产环境中使用更多核心：

_environment-production
OMP_NUM_THREADS=16

请注意，配置文件环境与默认的 _environment 合并，因此你只需要定义配置文件中变化的变量，并依赖其他变量的默认值。

Important

如果你需要使用环境变量指定密钥（例如访问令牌），你不应该使用配置文件环境（因为它们通常会被提交到版本控制）。我们将在下面的 管理密钥 中介绍推荐的技巧。

本地环境

在本地处理项目时，你可能希望为某些环境变量使用不同的值。例如，你可能希望添加一些变量，为 Python 执行提供额外的诊断输出。

你可以通过创建一个 _environment.local 文件来实现这一点。本地文件中的值将覆盖默认文件中指定的值：

_environment.local
PYTHONDEVMODE=1

请注意，_environment.local 不打算提交到版本控制。相反，它设计用于你只想在你的系统上激活的值。为此，Quarto 会自动将以下内容添加到你的项目 .gitignore 文件中：

.gitignore
/_*.local

这在你的环境变量包含密钥时特别有用，我们将在下一节中更深入地探讨。

管理密钥

通常，凭证或授权令牌通过环境变量提供给代码。在许多情况下，这些凭证是渲染项目所必需的（例如，如果项目正在访问远程数据库或 Web 服务中的数据）。

特别重要的是，这些凭证不应提交到版本控制。通常，这是通过以下组合实现的： 1. 在服务器或CI服务上运行时，将环境变量作为加密的秘密提供。不同服务的具体操作细节有所不同（GitHub Actions有部署秘密，Posit Connect支持内容变量等）。

  1. 对于本地开发，在_environment.local文件中定义变量（并忽略版本控制中的此文件，Quarto默认情况下会这样做）。例如，这里我们在本地环境文件中指定AWS凭证：

    _environment.local
    AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI

这留下了一个问题，即确保这些变量始终被指定。下一节关于必需变量的内容将介绍如何做到这一点。

必需变量

如果有某些环境变量需要指定才能渲染项目，你可以创建一个_environment.required文件。这个文件可以作为本地创作的起点复制到_environment.local，并且还可以作为服务器环境的文档，说明需要定义哪些变量。

回到AWS凭证的例子，这个_environment.required文件提供了文档，说明这些凭证在渲染项目时是必需的：

_environment.required
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

然后，.local文件（同样，不会被检入版本控制）将被填充实际的凭证：

_environment.local
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI

此外，任何希望渲染此项目的服务器环境都可以验证是否已指定必需的变量，如果未指定，则无法运行（并显示适当的错误消息）。