为每个环境设置环境变量

Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence…

Orbit 让你精确决定哪些构建可以看到哪些环境变量,这样生产凭证就不会出现在公开可访问的分支预览中。本指南涵盖作用域和优先级的工作原理、如何添加仅生产环境变量、暂存环境继承的行为方式,以及如何验证构建实际接收到的内容。

为什么这很重要

分支预览获得公开 URL。任何拥有链接的人都可以加载它。如果变量的作用域是每个环境,它会被注入到该预览的构建中,预览对它做什么,就用你的生产凭证做什么。

这就是本页存在的全部原因。下面的一切都是为了服务一条规则:生产机密属于生产作用域,其他地方都不行。

作用域的工作原理

每个变量都有一个作用域,它决定在构建时何时注入。

作用域	注入到
所有环境(项目范围)	此项目的每个构建,除非你限制它
特定环境覆盖	仅该环境的构建

当相同的键在两个级别都存在时,更具体的级别获胜。环境级覆盖胜过具有相同键的项目范围变量。Env vars 页面在所有环境部分的副标题中说明了这一点:项目范围变量在每个构建中可用,环境级覆盖优先。

项目范围变量也可以在不成为覆盖的情况下缩小范围。Available in 控制提供三种环境类型(production、staging、preview),你可以取消选择其中任何一种。

添加具有作用域的变量

在 Orbit 中打开你的项目,然后单击 Env vars 选项卡。
滚动到底部的 Add variable 表单。
填入 KEY 和 value。
使用 Scope 下拉菜单:
- All environments (project-wide) 将其注入到每个构建中。
- [Environment name] only ([type] override) 将其限定为该环境。
如果你选择了项目范围,使用 Available in 按钮取消选择此变量不应到达的环境类型。
对任何敏感信息勾选 Mark as secret。
单击 Add。

提交前,表单会告诉你它即将执行的操作。覆盖显示一条通知,说它仅适用于该环境的构建,项目范围变量在其他地方仍然适用。受限的项目范围变量显示它将被注入的确切环境类型。

添加仅生产环境变量

两个等效的路由:

在 Scope 下拉菜单中,选择你的生产环境(它带有绿色 production 徽章),或
保持作用域为 All environments,并在 Available in 下取消选择 staging 和 preview。

无论哪种方式,该变量在预览或暂存构建运行时都不存在。

"不存在"意味着不存在,而不是为空。在预览构建中读取 process.env.STRIPE_SECRET_KEY 的代码会得到 undefined,根据其编写方式,这可能在构建时抛出异常,或者更糟的是,静默地采取错误的分支。为预览提供测试模式值,而不是根本没有值。

安全模式

对大多数项目来说能干净地解决这个问题的模式:

添加 production 凭证,仅限生产环境。
添加具有 相同键 的变量,保存测试或沙盒值,在项目范围。

生产构建获得生产范围值,因为更具体的作用域获胜。预览和暂存获得测试值。任何地方都不会出现未定义的情况,生产凭证永远不会到达预览。

应用于:

生产数据库 URL
支付提供商密钥,对预览使用提供商的测试密钥
电子邮件发送密钥,使预览无法向真实客户发送邮件
管理员令牌和签名机密
任何有按次调用费用的东西

在暂存环境中继承生产变量

如果你的暂存环境接近生产,且你只想覆盖少数值,则无需复制所有内容。

在 Settings 中,找到 Staging: environment variables,并打开 Inherit production env vars。生产变量随后以 较低优先级 并入暂存构建,比任何你在暂存上明确设置的都低,所以你明确设置的任何内容仍然获胜。

继承将生产值复制到暂存构建中,包括生产凭证。仅在你的暂存环境受保护时才打开它。暂存支持密码和 IP 允许列表,位于 Settings 的 Staging: access protection 和 Staging: IP allowlist 部分。为不受保护的暂存环境打开继承会重新创建本页所述的确切暴露。

查看和编辑现有变量

Env vars 选项卡将变量分组为:

All environments 在顶部,保存项目范围变量
每个环境的可折叠部分,保存该环境的覆盖,带有数量计数

在它们上方是一个搜索框和一个 Secrets only 筛选器。

变量名旁边的徽章显示它到达的环境类型。显示 production 和 preview 但不显示 staging 的变量将从暂存构建中缺失,该徽章行是审核长列表的最快方式。

单击编辑图标可更改值。无法显示机密变量的当前值,只能替换。

在环境之间复制和比较

Copy variables between environments 将整个集合从一个作用域复制到另一个作用域。选择 From 和 To,可选择勾选 Overwrite variables that already exist in the target,然后单击 Preview 查看提交前将添加、更新和跳过多少个。

Env sync check 页面逐个键地比较生产和暂存,并报告仅在一个中存在的内容、具有不同值的内容以及匹配的内容。对于"暂存工作而生产不工作"的情况,或反之亦然,这是正确的第一站。

生产和暂存之间的值不同对大多数机密来说是正常且预期的。同步页面说明了这一点。你要寻找的是在一个环境中存在而在另一个环境中缺失的键。

跨项目共享变量

如果多个项目需要相同的凭证,请使用 env 组而不是将其粘贴到每个项目中。转到 Orbit,然后 Env groups,创建一个组,添加变量,并链接需要它们的项目。

组变量在构建时注入,并位于优先级顺序的底部:项目级和环境级变量都优先于组变量。你的帐户最多可以有 20 个组。

删除一个组会从每个关联项目的未来构建中删除这些变量。已完成的构建不受影响。

批量导入

Import .env 按钮打开一个粘贴框。粘贴 .env 文件,选择作用域,Orbit 会报告它找到了多少个变量以及它将标记为机密的有多少个。包含 SECRET、TOKEN、KEY、PASSWORD 等类似术语的键会自动标记。有一个 Overwrite existing variables with the same key 选项,默认关闭。

Download .env 生成一个仅包含变量名称的模板,没有值,用于与将提供自己的值的队友共享。

在导入对话框中选择作用域,然后再单击 Import,而不是之后。在项目范围导入整个生产 .env 会在一个操作中将每个生产凭证推送到预览构建中,修复方法是删除并重新添加它们,而不是更改设置。

验证构建实际接收到的内容

每个部署的详细信息页面列出在构建时注入的环境变量键,并根据你当前的配置将其与构建进行比较:已添加、已更改、已删除、未更改。青色键来自环境特定覆盖,灰色键来自项目级。

值永远不会被存储或显示。悬停在一个键会显示 SHA-256 指纹,足以确认两个环境是否保持相同的值,而不会暴露它。

如果配置在该部署构建后发生了更改,页面会使用 Environment variables updated since this deployment 通知说明这一点,并提醒你该更改在重新部署之前不会生效。

变量更改永远不会应用于已上线的部署。它们在构建运行时注入。更改应用依赖的任何内容后,重新部署。