环境变量

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

环境变量保存应用在构建时和运行时所需的配置和密钥，例如 API 密钥、数据库 URL 和功能开关，无需将任何内容存储在代码库中。本指南涵盖环境变量在 Orbit 中的位置、作用域和优先级如何工作、标记值为密钥、批量导入和导出，以及导致变量始终为 undefined 的常见错误。

位置

在 Orbit 中打开项目，然后点击 Env vars 选项卡，位置在 /orbit/<project-id>/env-vars。

页面分为几个部分：

顶部的所有环境：项目范围的变量，在每个构建中都可用。
每个环境（生产、暂存和任何预览）的可折叠部分，包含该环境的覆盖项。

列表上方有一个搜索框和仅密钥过滤器，这是快速浏览长列表的方式。

作用域工作方式

作用域	影响范围
所有环境（项目范围）	注入此项目的每个构建
环境级覆盖	仅应用于该环境，优先于具有相同键的项目范围值

页面副标题明确说明了规则：项目范围的变量在每个构建中都可用，环境级覆盖优先。

典型的设置是项目范围的 DATABASE_URL 指向测试数据库，生产级覆盖指向真实数据库。生产构建获得真实数据库，其他所有构建获得测试数据库，之后添加的任何内容都不会意外泄露生产凭证到预览中。

项目范围的变量还有一个可用于控制，允许从其他项目范围的变量中排除特定环境类型（production、staging、preview）。

关于按环境作用域的完整详情，包括安全原理，请参阅按环境设置环境变量。

项目范围的变量会注入分支预览构建中，而预览 URL 可被任何拥有链接的人公开访问。生产数据库凭证、实时支付密钥和管理员令牌必须仅限生产环境。这是此页面最为关键的设置要点。

添加变量

滚动到 Env vars 选项卡底部的添加变量表单。
输入键，例如 NEXT_PUBLIC_API_URL。
输入值。
选择作用域：**所有环境（项目范围）**或特定环境覆盖。
如果选择了项目范围，使用可用于按钮取消选择此变量不应到达的任何环境类型。
对于任何敏感内容，勾选标记为密钥。
点击添加。

表单在您提交前会告诉您它要执行的操作：环境覆盖显示通知说它仅应用于该环境的构建，受限项目范围的变量显示它将注入到哪些环境类型。

变更何时生效

添加、编辑或删除变量不会改变当前在线部署。变量在构建运行时注入，因此变更从下一次部署开始应用。在更改应用依赖的任何内容后重新部署。

Orbit 在这方面是明确的。打开部署的详情页面，如果配置自构建以来已更改，您会看到此部署后环境变量已更新通知，告诉您变更在重新部署前不会生效。

密钥

对于任何您不会粘贴到聊天中的内容，勾选标记为密钥：API 密钥、数据库密码、令牌、签名密钥。

密钥值在面板中被掩盖，并带有密钥徽章。非密钥值显示**（明文）**标记。

密钥值保存后无法读取，无论是您还是面板中的其他任何人都无法读取。您可以替换它（点击编辑图标、输入新值、保存），但无法显示它。在此处保存前，请在密码管理器中保留您自己的副本。

Orbit 还跟踪值已存在的时间长度，并在较旧的变量上显示年龄徽章，附带建议轮换的提示。这只是一个提醒，不是强制要求。

编辑和删除

点击变量旁的编辑图标以更改其值。点击删除以移除它，并确认：对话框警告依赖它的构建将会中断，这是下一次部署时将发生情况的准确描述。

批量导入和导出

选项卡顶部的两个按钮处理批量工作。

导入 .env 打开粘贴框。粘贴 .env 文件的内容，选择作用域，Orbit 告诉您它检测到多少个变量以及将标记为密钥的变量数。它根据名称自动标记密钥，因此包含 SECRET、TOKEN、KEY、PASSWORD 等内容的任何密钥在导入前都会标记为密钥。有使用相同键覆盖现有变量选项，默认关闭。

下载 .env 生成仅包含变量名称的模板，不包含值。它旨在与随后填入自己值的团队成员共享，而不是用作备份。

下载 .env 模板永远不包含值，包括非密钥变量。没有从 Orbit 导出值的方式。如果需要值的副本，请从最初生成值的地方获取。

在环境间复制变量

在环境间复制变量面板将整个集合从一个作用域复制到另一个作用域。选择从（项目级或特定环境）和到，可选择勾选覆盖目标中已存在的变量，然后点击预览以在您提交前准确查看将添加、更新和跳过多少个变量。

还有一个环境同步检查页面，按键比较生产和暂存环境，报告仅在其中一个中的内容、不同之处和匹配的内容。这是"为什么暂存工作但生产不工作"的正确工具。

在项目间共享变量

如果多个项目需要相同的凭证，使用环境组而不是将其复制到每个项目中。转到 Orbit，然后转到环境组，创建一个组，向其添加变量，然后链接需要这些变量的项目。

组变量在构建时注入，项目级和环境级变量优先于组变量。您在帐户上最多可以有 20 个组。

框架说明

哪些变量到达浏览器由您的框架决定，而不是由 Orbit 决定。Orbit 注入所有作用域内的内容；框架决定暴露什么。

Next.js：前缀为 NEXT_PUBLIC_ 的键在构建时内联到浏览器包中。其他所有内容保持服务器端。
Vite：前缀为 VITE_ 的键暴露给浏览器。其他所有内容仅在构建时有效。
Node.js 应用：作用域内的所有内容在构建期间位于 process.env 上，启用服务器模式时在运行时也是如此。

永远不要标记值为密钥，然后同时为其前缀 NEXT_PUBLIC_ 或 VITE_。密钥标记仅控制面板是否向您显示值；前缀控制您的框架是否将其发送到每个访问者的浏览器。前缀优先。

检查构建实际接收的内容

每个部署详情页面列出在构建时注入的环境变量键，并针对您的当前配置对其进行 diff：已添加、已更改、已移除和未更改。蓝绿色键来自环境特定覆盖，灰色键来自项目级。值永远不会存储或显示，但将鼠标悬停在键上会给出 SHA-256 指纹，足以确认两个环境保持相同值而无需显示它。

这是"我的变量是否真的到达构建"的决定性答案。在更改任何其他内容之前检查它。

故障排除

变量在运行时为 undefined。 检查部署是否在更改之后，然后检查作用域是否覆盖此环境，然后检查上面的框架前缀规则。按此顺序。

在生产中工作但在预览中不工作。 变量仅限生产环境，或项目范围的变量在可用于下取消选择了 preview。这通常是故意的。

在本地工作但在构建中不工作。 您的本地 .env 文件不在代码库中，也不应该在。使用导入 .env 导入它，并选择正确的作用域。

暂存缺少生产拥有的所有内容。 在设置中的暂存：环境变量下打开继承生产环境变量，或使用在环境间复制变量。