Orbit 中的分支预览部署

Branch previews build every non-production, non-staging branch you push to its own isolated URL, so you can click through a change in a real environment before it merges. This guide covers turning…

分支预览在 Orbit 中为每个非生产、非预发布分支构建一个隔离的 URL，以便您可以在实际环境中点击查看更改，然后再合并。本指南涵盖如何打开分支预览、URL 的来源、预览的清理方式以及如何防止预览构建泄露生产密钥。

启用分支预览

在 Orbit 中打开您的项目。
打开 Settings 选项卡。
找到 Runtime 部分并打开 Branch previews。

启用后，每次推送到既不是生产分支也不是预发布分支的分支都会触发构建，并将其部署到其自己的预览环境。

Orbit 项目设置中的分支预览切换开关

分支预览是按项目切换的功能，不是付费附加功能。它在每个 Orbit 计划上都可用，包括免费的 Launch 计划。不同计划的区别在于单个项目一次可以有多少个环境：Launch 允许 2 个（生产加一个预览）、Liftoff 4 个、Apex 11 个。一旦项目达到其环境限制，进一步的分支将不会获得自己的预览，直到您删除一个。

预览 URL

预览会获得从其分支名称派生的主机名：名称转换为小写，每个不是字母、数字或连字符的字符都变成连字符，连字符的连续出现会合并，结果被截断为 48 个字符，并以 branch- 为前缀。

分支	预览主机名
`redesign`	`branch-redesign.kaps.run`
`feat/new-checkout`	`branch-feat-new-checkout.kaps.run`
`JB/Fix_Cart`	`branch-jb-fix-cart.kaps.run`

预览 URL 可公开访问任何拥有链接的人。它们不会被索引或宣传，但也不受访问控制。不要使用预览来审查任何不能离开您的团队的内容，也不要将预览指向生产数据。如果您需要受保护的预生产环境，请改用 staging 环境：staging 在 Settings 中的 Staging: access protection 和 Staging: IP allowlist 部分支持密码和 IP 允许列表。

预览出现的位置

项目 Overview 选项卡有一个 Preview deployments 部分，列出每个活跃的预览。每行显示:

分支名称和 PR #number 徽章（当分支有打开的拉取请求时链接到该拉取请求）
当前状态（QUEUED、BUILDING 或实时）
多久前部署的
打开预览 URL 的链接
View logs 打开部署详情页面
删除按钮

每个预览都是一个完全隔离的环境，拥有自己的 URL、自己的构建和自己的环境变量。它做的任何事情都不会影响生产。

项目 Branches 选项卡提供按分支组织的相同信息，当您同时打开多个分支时更容易扫描。

预览中的环境变量

这是值得正确处理的部分。作用域为 All environments (project-wide) 的变量被注入到预览构建中，预览 URL 是公开的。

将生产凭证的作用域限制为仅您的生产环境。
为第三方服务提供预览测试模式或沙箱凭证。
永远不要在项目范围内保留生产数据库 URL 或实时支付密钥。

完整的机制，包括如何添加仅限生产的变量以及预发布继承如何工作，请参阅 Setting Environment Variables Per Environment。

预览的构建日志

单击任何预览旁边的 View logs 以打开其部署详情页面。预览的处理方式与生产部署相同：完整的流式构建日志、构建阶段、提交和作者、工件大小、缓存命中或冷构建、检测到的框架和包管理器，以及当构建失败时的 AI 诊断按钮。

删除预览

单击预览行上的删除按钮并确认。

删除预览会删除环境及其整个构建历史，而不仅仅是当前部署。这无法撤销。分支本身保持不变，因此再次推送到它会从头创建一个新的预览，没有历史记录和冷构建缓存。

自动清理

您不必自己整理。

当拉取请求关闭或合并时，其预览环境会立即暂停并停止提供服务。访问者会获得 404 而不是过时的构建。
删除分支会以相同的方式暂停该分支的预览。
暂停的预览大约在一天后被垃圾收集：源代码 tarball、构建工件和构建缓存被删除，环境被归档。

您也可以按计划使预览过期。在 Settings 中，找到 Preview expiry 并选择 Never、7、14、30 或 60 天。早于该时间的预览会自动暂停并在 24 小时内清理。

在繁忙的仓库上，将 Preview expiry 设置为 14 或 30 天。每个活跃预览都计入您的项目的环境限制，过期的预览通常是新分支静默地无法获得预览的原因。

批准和预览

如果在 Deploy protection 下启用了 Require approval for production，它仅适用于生产。预览构建不会被保留以等待批准。

要停止特定预览部署进一步的更改而不删除它，从 Environments 选项卡暂停环境。对暂停的环境的新部署会被跳过，直到您恢复它。

故障排除

分支已推送但未出现预览。 依次检查：Settings 中的 Branch previews 然后 Runtime 是否打开？分支实际上是您的预发布分支吗（预发布部署到预发布，而不是预览）？分支是否与您的 Branch ignore patterns 之一匹配，例如 dependabot/*？项目是否已达到您的计划的环境限制？

预览已构建但显示 404。 构建成功，但此分支的输出目录可能不正确。检查 Settings 中的 Output directory，请记住分支可以在不更改设置的情况下更改构建输出。请参阅 Configuring Your Build Command and Output Directory。

预览显示较旧的提交。 在同一分支的构建仍在运行时推送新提交会取消进行中的构建并启动新的构建。如果您看到已取消的部署后跟正在运行的部署，这是预期的。等待第二次构建。

已关闭的 PR 的预览仍然可访问。 暂停发生在 webhook 事件上。如果在关闭 PR 时提供程序连接已断开，该事件永远不会到达。从 Overview 选项卡手动删除预览。