构建和预览故障排查

从这里开始

当智能体完成任务后，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. 在可用时，于设计模式中选择损坏的元素。
3. 描述预期的移动端布局，以及哪些内容不能改变。
4. 每次只应用一项更改，然后验证桌面端和移动端视图，以及加载、空状态、悬停和错误状态。

图片或其他资源缺失

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

智能体改错了元素或破坏了其他区域

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

报告问题

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

从项目聊天中打开 Feedback

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

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

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

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

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

问题修复后

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

常见问题

为什么 App 预览会显示空白白屏？

1. 确认问题是仅影响 App 预览，还是 Preview URL 或已发布站点也同样受影响。
2. 选择一次重新加载 App 预览，在新标签页中打开 Preview，并测试无痕窗口。
3. 检查当前任务或构建是否仍在运行。等待其完成后再重试。
4. 如果有明确信息提示 Cloud & AI 余额不足或应用已被暂停，请打开 Settings → Cloud & AI 并查看该余额。不要仅凭空白屏幕就进行充值。
5. 记录任何控制台或网络错误，但不要分享 cookies、tokens 或机密值。

如果屏幕仍然空白，请联系支持团队，并提供聊天链接、完整的 Viewer URL、时间和时区、受影响的环境、截图以及已脱敏的错误详情。