构建与预览故障排查

当构建失败或预览无法加载时，请从第一个可见错误开始，并按照该症状对应的恢复路径逐步排查。本页涵盖 App 预览、Preview、构建错误，以及在报告问题之前应采取的步骤。

从这里开始

在智能体完成任务后，App 预览会加载你的应用。终端会显示任务活动和错误，而 App 预览工具栏会提供“重新加载 App 预览”控件、设备视图切换、在新标签页中打开预览的选项，以及控制台。

1. 保存最新更改，并等待当前任务或构建完成。
2. 如果预览看起来不是最新状态，或一直停留在加载界面，请选择一次 重新加载 App 预览。
3. 如果嵌入式 App 预览卡住或无响应，请在新标签页中打开预览。
4. 打开 控制台 并复制第一个可见错误。保留项目链接和失败发生的时间。

当构建失败时

先尝试 Resolve

当 Atoms 检测到构建问题时，左下角会出现 问题报告 通知。如果通知中包含 Resolve，请先进行一次修复尝试，再执行其他操作。

1. 选择 Resolve 并等待当前尝试完成。
2. 在其运行期间，不要再次选择 Resolve。
3. 如果该尝试未完成，请记录可见状态，并继续执行下方的报告步骤。不要再次发起 Resolve 尝试。
4. 当尝试完成后，检查已刷新的预览。如果没有更新，请刷新一次浏览器。
5. 重复触发该问题的操作。如果问题仍然存在，请展开 问题报告 并继续执行下方的报告步骤。

构建错误或缺少依赖项

如果 Preview 面板显示构建错误、红色错误横幅，或提示缺少包，请使用准确的错误信息来缩小下一步排查范围。

1. 打开 控制台 并复制其中可见的完整错误信息。
2. 如果 Resolve 可用，请使用一次并等待尝试完成。
3. 如果没有 Resolve 按钮，请将准确的错误信息粘贴到项目聊天中，并让智能体修复该构建错误。
4. 如果错误是在某次特定更改后开始出现的，请打开 History 并将当前版本与最后一个正常工作的版本进行比较。
5. 如果错误难以定位，请从最后一个稳定版本执行 克隆，然后逐步重新应用更改。

如果错误提到 App 预览、启动脚本、Publish、部署记录或第三方包的内部文件，可能表示这是平台问题。联系支持团队时，请附上完整错误信息。

构建一直处于进行中

重试前，请先在终端中检查当前任务活动。如果任务或构建仍在运行，请等待其完成。如果当前尝试结束后仍显示进行中，请记录状态、时间戳、项目链接以及任何可见的错误详情，然后报告该问题。

当 Preview 或 App 预览无法加载时

加载界面或无响应的预览

首先检查受影响的是否仅为嵌入式 App 预览，还是 Preview URL 和已发布站点也同样受影响。

1. 确认当前任务或构建是否仍在运行。
2. 选择一次 重新加载 App 预览。
3. 在新的浏览器标签页中打开 Preview。
4. 在无痕窗口中测试相同的 URL。
5. 如果最后一个已知正常工作的版本可以加载，请将其与最近引入问题的更改进行比较。

如果产品明确提示 Cloud & AI 余额不足或应用已暂停，请打开 Settings → Cloud & AI 并检查该状态。不要仅凭空白屏幕就进行充值。

空白或不完整的预览

检查空白屏幕影响的是整个应用，还是仅影响某个页面或组件。如果仅有一个区域受影响，请使用页面选择器直接打开该页面，并重复执行到达该页面的最小用户路径。如果整个预览都是空白，请返回构建结果，先解决第一个构建或运行时错误，再重新测试。

记录任何控制台或网络错误，但不要共享 cookies、tokens 或机密值。如果问题持续存在，请在报告中附上已脱敏的错误详情。

Preview 显示的是旧版本

Preview 和已发布站点是两个独立通道。刷新预览前，请确认最新更改已保存，且最新构建已完成。构建完成后重新打开 Preview。如果仍显示旧内容，请在 History 中将当前版本与最后一个已知正常工作的版本进行比较。

当预览显示异常时

交互或导航无法使用

页面能够渲染，并不等于页面能够正常工作。请打开每个重要的导航链接，点击主要按钮，提交关键表单，并从头到尾走完整个主要用户路径。当某个交互失败时，请记录预期结果停止生效的准确操作步骤，并在每次修正后再次测试该路径。

移动端布局损坏

1. 使用 App 预览工具栏中的设备切换按钮切换到移动视图。
2. 在可用时，于 Design 模式中选择损坏的元素。
3. 说明预期的移动端布局，以及哪些内容不能改变。
4. 应用一项更改后，验证桌面端和移动端视图，以及加载、空状态、悬停和错误状态。

图片或其他资源缺失

1. 打开 Files 部分并确认被引用的文件存在。
2. 检查路径、文件名和格式是否与应用使用的引用一致。
3. 如果资源最近被移动或重命名，请恢复引用或有意地更新引用。
4. 选择重新加载 App 预览，并再次测试受影响的页面。

智能体修改了错误的元素，或破坏了其他区域

1. 打开 History，并从最后一个稳定版本执行 克隆。
2. 在可用时，使用 Design 模式精确定位目标元素。
3. 说明哪些内容不能改变，并且每个提示词只做一项更改。
4. 验证结果后，再继续进行下一项更改。

报告问题

当 Resolve 不可用、已完成的 Resolve 尝试后问题仍然存在、Preview 无响应但项目聊天仍可使用，或智能体调查后异常行为仍持续时，请报告该问题。

从项目聊天中打开反馈

1. 打开受影响的项目聊天，并找到最新的相关智能体消息。
2. 选择 ...（更多选项），然后选择 Feedback。
3. 在支持消息窗口中，选择 Send us a message；如果已存在会话，请在该现有会话中发送报告。

完整的问题报告流程，请参阅 报告问题。

提供足够的细节以重现问题

• 问题摘要。 用一到两句话描述问题。
• 项目或聊天链接。 附上问题发生位置的 URL。
• 日期和时间。 包含你的时区。
• 重现步骤。 按顺序列出准确操作。
• 预期结果与实际结果。 说明本应发生什么，以及实际发生了什么。
• 你已经尝试过的操作。 说明是否出现了 Resolve、它完成后发生了什么，以及刷新或克隆是否改变了结果。
• 浏览器和设备。 包括浏览器、操作系统和设备类型。
• 证据。 附上截图或录屏，以及相关的可见问题报告或控制台详情。

在分享截图或日志之前，请移除密码、API 密钥、身份验证 tokens、cookies、支付详情，以及无关的个人或机密数据。

问题修复后

从头到尾运行主要用户路径。检查桌面端和移动端视图中的 Preview，从页面选择器打开每个页面，并确认控制台中没有红色错误信息。如果应用已准备好发布，请替换所有占位内容，并在 App 预览中完成发布检查。

常见问题