Orbit
部署您的项目
Once a repository is connected, Orbit deploys on every push to your production branch: it clones the commit, installs dependencies, runs your build, packages the output and starts serving it. This…
一旦连接了存储库，Orbit 在每次推送到生产分支时进行部署：它克隆提交、安装依赖项、运行构建、打包输出并开始提供服务。本指南涵盖完整的部署周期、如何手动触发部署，以及控制何时允许部署上线的设置。
自动部署如何工作
每次推送到在"设置"中"Git"下设置为"生产分支"的分支都会触发部署。Orbit 随后会：
- 从 GitHub、GitLab 或 Bitbucket 接收推送事件。
- 将部署加入队列并为其分配一个构建槽。
- 在该确切提交处克隆您的存储库。
- 如果您的计划上提供了构建缓存，则恢复缓存的
node_modules。 - 运行您的安装命令（
npm ci、yarn install或pnpm install，从您的锁定文件检测）。 - 运行您的构建命令。
- 将输出目录打包到部署制品中并上传。
- 切换环境以提供新制品。
部署详情页面将这些显示为命名的"构建阶段"：Clone、Cache restore、Install、Cache save、Build、Upload、Done。大多数项目在一到三分钟内完成。
部署状态
| 状态 | 含义 |
|---|---|
| Queued | 等待构建槽。部署页面显示您在队列中的位置 |
| Awaiting approval | 由于"需要生产环境批准"已打开而被保留。某人必须批准它 |
| Building | 正在安装依赖项并运行构建命令 |
| Deploying | 构建完成，新制品正在投入流量 |
| Succeeded (显示为 Live) | 提供流量。部署带有"CURRENT"徽章 |
| Failed | 构建或部署步骤出错。打开日志查看出错位置 |
| Cancelled | 在完成前停止，由您或同一分支的新推送停止 |
| Rolled back | 被回滚到更早版本所取代 |
观察进行中的构建
项目"概览"在"最新构建"面板中显示当前构建和实时流日志。点击"完整详情"打开部署详情页面，该页面添加了构建进度条、估计剩余时间、队列位置和按阶段划分的构建时间线。
如果您的计划允许多个并发构建且它们都很繁忙，该页面会明确告诉您：它显示您有多少个并发构建槽正在使用，并在其中一个释放时自动启动您的部署。您可以在"Orbit"中查看所有项目中的每个构建，然后是"Queue"。
手动触发部署
有四种方法可以在不推送新提交的情况下部署。
重新部署最新提交
- 打开项目。
- 打开"部署"选项卡。
- 点击您想要的部署以打开其详情页面。
- 点击"重试构建"。如果您怀疑缓存的依赖项陈旧，请使用"更多重试选项"，然后"使用已清除缓存重试"。
立即部署
"部署"选项卡上的"立即部署"按钮将您的生产分支当前 head 的新构建加入队列。
计划部署
部署可以计划在将来的时间进行。Orbit 在您计划部署时对提交进行快照，因此稍后运行的构建是您批准的代码，而不是同时落地的任何代码。
部署钩子
部署钩子是一个密钥 URL，当某个东西向它发送 POST 请求时，它会将构建加入队列。使用它们从无头 CMS、cron 作业或 CI 管道重建。在项目的"Hooks"选项卡上进行设置。请参阅通过部署钩子触发部署。
构建设置
Orbit 为大多数项目检测合理的默认值。在"设置"中"构建设置"中覆盖其中任何一个：
| 字段 | 留空时的占位符 | 示例 |
|---|---|---|
| Install command | npm ci (auto-detected) | npm ci、yarn install --frozen-lockfile、pnpm install |
| Build command | npm run build (auto-detected) | npm run build、next build、vite build、astro build |
| Output directory | dist (auto-detected) | dist、.next、out、build、.output |
| Root directory | / (monorepo subdirectory) | apps/web |
| Node.js version | 平台默认值 | 18、20、22 |
将字段留空以保持自动检测的值。完整的详情（包括各个框架的值和导致首次部署失败的错误）在配置您的构建命令和输出目录中。
设置"根目录"不仅仅改变工作目录。仅改变该路径外文件的推送会自动跳过，因此单仓库不会在每个提交上重建每个应用。
决定何时允许部署
Orbit 有多个独立的门。它们都在"设置"中。
部署锁定
使用锁定在事故、维护窗口或代码冻结期间冻结生产。
- 打开项目。
- 点击"锁定部署"。
- 添加可选的原因。
锁定时，推送触发的部署会被静默跳过，横幅显示"生产部署已锁定"及您的原因。手动部署仍然有效，这是故意的：锁定阻止意外部署，而不是您尝试发送的修复。点击"解除部署锁定"以解除它。
需要生产环境批准
在"部署保护"下打开"需要生产环境批准"。推送触发的生产部署随后会暂停在"等待批准"，直到某人打开部署并点击"批准"或"拒绝"。面板部署和部署钩子不受影响。
需要暂存成功优先
"需要暂存成功在生产之前"会保留推送触发的生产部署，直到暂存环境已成功部署同一提交。某人仍然可以手动批准以跳过等待。
CI 必需的检查
在"CI 必需的检查"下在您自己的 CI 上进行部署。在 GitHub 上，输入逗号分隔的 Actions 作业名称，所有作业都必须通过。在 GitLab 上，任何非空值都会等待整个管道。CI 失败会自动取消 Orbit 部署。
部署冻结计划
"部署冻结计划"在批准的窗口外阻止推送触发的部署：周末阻止、允许的小时范围或两者兼有。所有时间都是 UTC。手动部署和部署钩子不受影响。
除了部署冻结之外的上述每个门都只阻止推送触发的部署。部署钩子和手动面板部署直接通过。如果钩子 URL 泄露，这些设置都不会阻止它将构建加入队列。像对待凭证一样对待钩子 URL。
跳过您不需要的构建
- 忽略的路径：逗号分隔的 glob 模式。如果推送中的每个文件都匹配，则构建被跳过。
*.md,docs/**会停止文档提交触发部署。 - 分支忽略模式：来自匹配分支的推送完全被跳过。
dependabot/*,renovate/*是常见情况。 - Git 标签部署：在推送匹配标签时使用 glob（如
v*）部署到生产。
构建缓存
Orbit 在 Liftoff 和 Apex 计划上在构建之间缓存 node_modules。当使用缓存的安装时，部署显示"缓存命中"徽章，安装阶段显著更短。冷构建改为显示"冷构建"。
要强制完全重新安装，打开"设置"，然后"清除构建缓存"，并确认。每个环境的下一个部署从头开始运行完整安装。
如果构建以您无法解释的方式失败，且代码在本地很好，在开始更改任何内容之前使用已清除的缓存重试它。陈旧的缓存依赖树是一个常见且非常令人困惑的原因。
当部署出现问题时
Orbit 可以为您捕捉糟糕的部署，而不是让它保持实时：
- 故障时自动回滚在生产部署失败时自动恢复上一个健康的部署。
- 健康检查在每个生产部署后获取您选择的路径。15 秒内的非 2xx 响应会恢复上一个健康的部署。
- 烟雾测试在每个成功部署后针对多达 10 个路径运行 GET 请求，并记录通过或失败。结合自动回滚，失败的烟雾测试会回滚部署。