Orbit
Kapsule Migrator 构建失败问题排查
When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…
排查失败的构建
当 Orbit 构建失败时，部署详情页面会为您提供完整日志、分类的失败摘要和建议的修复方案。本指南将帮助您理解该页面的内容、Orbit 能够识别的失败类型、无法识别的失败类型，以及构建成功但网站仍然出错时该做什么。
阅读失败信息
- 在 Orbit 中打开您的项目。
- 打开部署选项卡。
- 点击状态为失败的部署。
- 先阅读日志上方的失败摘要，然后再阅读日志本身。
Orbit 为每个失败分配一个类别：内存不足、编译错误、测试失败、Lint 错误、安装错误、网络错误、超时或未知错误。该类别会告诉您在阅读任何日志行之前应该查看管道的哪个部分。
还有一个获取 AI 诊断按钮。它会读取日志的最后 120 行以及检测到的框架和失败类别，然后返回一个用通俗语言解释的说明。
诊断标记为由 AI 生成，使用前请验证。将其视为指向日志中正确行的很好指针，而不是您代码库的权威。在更改任何内容之前，请先阅读它所指的行。
如果构建从未启动且卡在已排队状态，请跳到下面的已排队构建部分。
Orbit 按名称识别的失败
这些会在部署页面上提供具体的建议修复方案。
| Orbit 检测到的内容 | 含义 | 修复 |
|---|---|---|
| 缺少模块 | 导入指向未安装的软件包 | 将软件包添加到 package.json 并提交，或修复导入路径中的拼写错误 |
ERESOLVE 冲突 | npm 无法满足对等依赖关系 | 在 package.json 中解决冲突，或将 --legacy-peer-deps 添加到设置中的安装命令 |
| TypeScript 错误 | 构建期间类型检查失败 | 修复列出的错误。对于第三方类型问题，在 tsconfig.json 中 skipLibCheck: true |
| 内存不足 | 构建超过了构建机器的 RAM | 添加 NODE_OPTIONS=--max-old-space-size=2048 作为环境变量，或迁移到具有更大构建机器的计划 |
| 构建磁盘已满 | 构建填满了其磁盘 | 查找意外大的 node_modules 或工件，或迁移到具有更大构建磁盘的计划 |
| 构建超时 | 构建达到 30 分钟中止 | 启用构建缓存、减少包大小或找到正在挂起的内容 |
| 未找到软件包 (404) | 依赖项不存在于该名称或版本 | 检查 package.json 是否有拼写错误，或确认软件包已发布 |
| ESLint 错误 | Lint 错误导致构建失败 | 修复它们，或在框架配置中停止 lint 导致构建失败 |
| 语法错误 | 无法解析的源代码 | 缺少括号、未闭合的字符串或 Node 版本不支持的语法 |
| 文件未找到 | 存储库中不存在引用的文件 | 确认它已提交，并检查路径的大小写 |
| 锁定文件已过期 | 锁定文件与 package.json 不匹配 | 在本地运行您的软件包管理器的安装并提交更新的锁定文件 |
锁定文件不匹配是最常见的首次部署失败，也是最令人困惑的，因为它从不在本地发生。npm ci、yarn install --frozen-lockfile 和 pnpm install --frozen-lockfile 在锁定文件与 package.json 不一致时都拒绝继续。在本地重新生成锁定文件并提交它。
按阶段分类的常见失败
依赖项安装失败
安装阶段出错。
- 错误的软件包管理器。 Orbit 从您的锁定文件中选择 npm、yarn 或 pnpm。如果提交了多个锁定文件，选择可能不是您期望的那个。删除您不使用的文件，或在设置中明确设置安装命令。
- 私有注册表。 如果依赖项来自私有注册表，身份验证令牌必须在构建时作为环境变量可用，并且您的
.npmrc必须引用它。 - Node.js 版本不匹配。 某些软件包需要最低 Node 版本。在设置中将 Node.js 版本设置为主版本号：
18、20或22。 - 大型 monorepo 上内存不足。 使用
npm ci而不是npm install，并考虑迁移到具有更大构建机器的计划。
构建命令失败
构建阶段出错。
- TypeScript 或 lint 错误。 Orbit 完全按照写入的方式运行您的构建命令。如果您的构建在本地失败，它也会在这里失败。
- 缺少构建时环境变量。 在构建期间读取的变量必须在构建运行之前存在，而不仅仅是在运行时。在环境变量选项卡上添加它并重新部署。部署后添加的构建时变量不会溯及既往地应用于它。
- monorepo 中根目录错误。 在设置中将根目录设置为应用程序的路径，例如
apps/web。
构建超时
每个计划上的构建在 30 分钟的实际运行时间后都会被中止。如果您的构建一致性地接近该时间：
- 检查日志中是否有进程等待输入。提示用户输入的构建是挂起的构建。
- 避免在大型依赖树上使用
--legacy-peer-deps，除非您需要它。 - 确保正在使用构建缓存。Liftoff 和 Apex 计划包含它；部署页面显示缓存命中或冷构建。
- 迁移到具有更多构建 vCPU 的计划。请参阅 Orbit 计划限制。
构建从未启动
卡在已排队的部署正在等待构建槽位。详情页面显示您的队列位置以及有多少并发构建槽位正在使用中，并在一个槽位空闲时自动启动构建。Launch 和 Liftoff 允许一个并发构建；Apex 允许三个。
您可以在 Orbit 然后队列中查看整个帐户中的所有正在进行的内容。
如果部署在没有任何其他内容运行的情况下卡在已排队状态，则更可能是被保留而不是排队。检查：
- 等待批准，如果要求对生产进行批准已打开
- 项目上的部署锁定
- 部署冻结计划阻止当前时间或日期
- CI 必需检查等待您的管道
- 生产前需要暂存成功等待同一提交的暂存部署
构建被完全跳过
如果推送没有产生任何部署，则可能是有意被过滤的：
- 忽略的路径：推送中的每个文件都匹配一个模式，如
*.md或docs/** - 分支忽略模式：分支匹配的内容如
dependabot/* - 根目录：推送没有涉及该项目的 monorepo 子目录
- 分支预览关闭，推送不是针对生产或暂存
构建成功但网站出错
绿色构建和损坏的网站几乎总是配置问题而不是代码问题。
每个页面都显示 404。 输出目录错误：Orbit 发布了不是您构建输出的文件夹。检查您的构建实际写入的内容。常见值包括 dist、.next、out、build 和 .output。
仅动态路由上显示 404。 应用程序需要运行的服务器，但被用作静态文件提供。在设置中的运行时下打开服务器模式。这是 Next.js with SSR、Remix、Nuxt 和任何其他非静态导出的应用程序所必需的。
部署后资产 404，对于已在网站上的用户。 他们加载了旧页面，并请求不再存在的旧捆绑包 URL。在设置中打开倾斜保护，这样可以在新部署上线后的保留窗口内保留前一个构建的工件。
环境变量在运行时未定义。 确认变量的作用域确实涵盖此环境，并且部署日期在更改后。部署详情页面列出了在构建时注入的确切键，并将它们与当前配置进行对比。
特定框架的构建设置位于配置您的构建命令和输出目录中。
重试
在失败的部署页面上：
- 重试构建重新运行相同的提交。
- 更多重试选项，然后清除缓存并重试，首先删除构建缓存。
您也可以让 Orbit 为您重试。设置中的构建自动重试会重新排队因基础设施错误（如网络故障或超时）导致的失败构建，最多三次。它故意不重试代码错误，因此编译、lint 或测试失败永远不会循环。
使用清除缓存重试会删除环境的缓存 node_modules 且无法撤销。它之后的下一个构建会很慢。这是目的，但不要在大型 monorepo 上下意识地这样做。
停止坏的构建到达用户
如果部署已经上线并破坏了某些内容，请回滚而不是在压力下尝试向前修复。回滚会提升已构建的工件，只需几秒钟。请参阅回滚部署。
要在您调查时停止进一步的部署，请在项目上点击锁定部署。推送触发的部署将被跳过，直到您解锁，而手动部署仍然可以工作，以便您可以提交修复。
您也可以让 Orbit 自动执行此操作：失败时自动回滚会在生产部署失败时恢复最后一个健康部署，健康检查路径在新部署在 15 秒内没有使用 2xx 应答时恢复它。
仍然卡住
如果日志简单地以没有错误消息的方式结束，构建进程很可能被杀死：内存不足或构建机器被回收。重试一次。如果它以相同的方式失败两次，请从 KPanel 打开工单或发送电子邮件至 support@kapsulehost.com 并包含详情页面上显示的部署 ID。