建置與預覽疑難排解

從這裡開始

當智能體完成任務後，App 預覽會載入你的 app。終端會顯示任務活動與錯誤，而 App 預覽工具列會提供你重新載入 App 預覽的控制項、裝置檢視切換、在新分頁中開啟預覽的選項，以及 Console。

1. 儲存最新變更，並等待目前的任務或建置完成。
2. 如果預覽看起來不是最新狀態或停留在載入畫面，請選取一次 Reload App Viewer。
3. 如果內嵌的 App 預覽卡住或沒有回應，請在新分頁中開啟預覽。
4. 開啟 Console 並複製第一個可見錯誤。請保留專案連結與失敗發生的時間。

當建置失敗時

先嘗試 Resolve

當 Atoms 偵測到建置問題時，左下角會出現 問題報告 通知。如果通知中包含 Resolve，請先進行一次修復嘗試，再採取其他動作。

1. 選取 Resolve 並等待目前的嘗試完成。
2. 在執行期間不要再次選取 Resolve。
3. 如果嘗試未完成，請記錄可見狀態，然後繼續進行下方的回報步驟。不要再開始另一個 Resolve 嘗試。
4. 當嘗試完成後，檢查重新整理後的預覽。如果沒有更新，請重新整理瀏覽器一次。
5. 重複造成問題的操作。如果問題仍然存在，請展開 問題報告 並繼續進行下方的回報步驟。

建置錯誤或缺少相依套件

如果 Preview 面板顯示建置錯誤、紅色錯誤橫幅，或關於缺少套件的訊息，請使用精確訊息來縮小下一步的範圍。

1. 開啟 Console 並複製其中可見的完整錯誤訊息。
2. 如果 Resolve 可用，請使用一次並等待嘗試完成。
3. 如果沒有 Resolve 按鈕，請將精確錯誤貼到 Project chat，並請智能體修正該建置錯誤。
4. 如果錯誤是在某次特定變更後開始出現，請開啟 History 並比較目前版本與上一個可正常運作的版本。
5. 如果錯誤難以隔離，請從上一個穩定版本進行 克隆，並逐步重新套用變更。

提到 App 預覽、啟動指令碼、Publish、部署記錄，或第三方套件內部檔案的錯誤，可能表示是平台問題。聯絡 Support 時請附上完整錯誤訊息。

建置持續顯示進行中

重試前，先檢查終端中的目前任務活動。如果任務或建置仍在執行，請等待其完成。如果目前嘗試結束後仍顯示進行中，請記錄狀態、時間戳記、專案連結，以及任何可見的錯誤細節，然後回報問題。

當 Preview 或 App 預覽無法載入時

載入畫面或無回應的預覽

先確認是否只有內嵌的 App 預覽受到影響，或 Preview URL 與已發佈網站也同樣受到影響。

1. 確認目前的任務或建置是否仍在執行。
2. 選取一次 Reload App Viewer。
3. 在新的瀏覽器分頁中開啟 Preview。
4. 在無痕視窗中測試相同的 URL。
5. 如果上一個已知可正常運作的版本可以載入，請將其與最近引入問題的變更進行比較。

如果產品明確回報 Cloud & AI 餘額不足或 app 已被停用，請開啟 Settings → Cloud & AI 並檢查該狀態。不要只因為空白畫面就進行儲值。

空白或不完整的預覽

請確認空白畫面影響的是整個 app，還是只有某個頁面或元件。如果只有某個區域受影響，請使用頁面選擇器直接開啟該頁面，並重複最小的使用者操作流程以到達該頁面。如果整個預覽都是空白，請回到建置結果，先解決第一個建置或執行階段錯誤，再重新測試。

請記錄任何 Console 或 Network 錯誤，但不要分享 cookies、tokens 或機密值。如果問題持續，請在回報中附上已去識別化的錯誤細節。

Preview 顯示較舊版本

Preview 與已發佈網站是不同的通道。重新整理預覽前，請確認最新變更已儲存，且最新建置已完成。建置完成後重新開啟 Preview。如果仍顯示較舊內容，請在 History 中比較目前版本與上一個已知可正常運作的版本。

當預覽看起來不正確時

互動或導覽無法運作

能夠渲染的頁面不等於能正常運作的頁面。請開啟每個重要的導覽連結、按下主要按鈕、提交關鍵表單，並從頭到尾走完主要使用者流程。當某個互動失敗時，請記錄預期結果中斷的確切操作，並在每次修正後再次測試該路徑。

行動版版面配置損壞

1. 使用 App 預覽工具列中的裝置切換，切換到行動版檢視。
2. 可用時，在 Design mode 中選取損壞的元素。
3. 說明預期的行動版版面配置，以及哪些內容不得變更。
4. 套用一項變更後，驗證桌面版與行動版檢視，以及載入、空狀態、hover 與錯誤狀態。

圖片或其他素材遺失

1. 開啟 Files 區段並確認被參照的檔案存在。
2. 檢查路徑、檔名與格式是否與 app 使用的參照一致。
3. 如果素材最近被移動或重新命名，請還原參照或刻意更新它。
4. 選取 Reload App Viewer，然後再次測試受影響的頁面。

智能體變更了錯誤的元素或破壞了其他區域

1. 開啟 History，並從上一個穩定版本進行 克隆。
2. 可用時，使用 Design mode 鎖定精確元素。
3. 說明哪些內容不得變更，並且每個提示詞只做一項變更。
4. 驗證結果後，再繼續下一項變更。

回報問題

當 Resolve 無法使用、問題在完成的 Resolve 嘗試後仍然存在、Preview 沒有回應但 Project chat 仍可使用，或智能體調查後仍持續出現非預期行為時，請回報問題。

從 Project chat 開啟 Feedback

1. 開啟受影響的 Project chat，並找到最新的相關智能體訊息。
2. 選取 ...（更多選項），然後選取 Feedback。
3. 在支援訊息工具中，選取 Send us a message，如果已存在對話，請在現有對話中送出回報。

如需完整的問題報告流程，請參閱 回報問題。

提供足夠細節以重現問題

• 問題摘要。 用一到兩句話描述問題。
• Project 或 Chat 連結。 附上發生問題的 URL。
• 日期與時間。 請包含你的時區。
• 重現步驟。 依序列出精確操作。
• 預期結果與實際結果。 說明原本應該發生什麼，以及實際上發生了什麼。
• 你已經嘗試過的內容。 說明是否出現 Resolve、它完成後發生了什麼，以及重新整理或克隆是否改變結果。
• 瀏覽器與裝置。 請包含瀏覽器、作業系統與裝置類型。
• 佐證資料。 附上螢幕截圖或錄影，以及相關的可見問題報告或 Console 細節。

分享螢幕截圖或日誌前，請移除密碼、API 金鑰、驗證 tokens、cookies、付款資訊，以及不相關的個人或機密資料。

問題修正後

從頭到尾執行主要使用者流程。檢查桌面版與行動版檢視中的 Preview，從頁面選擇器開啟每個頁面，並確認 Console 沒有紅色錯誤訊息。如果 app 已準備好發佈，請替換任何預留內容，並在 App 預覽中完成發佈檢查。

常見問題

為什麼 App 預覽會顯示空白白色畫面？

1. 確認問題是否只影響 App 預覽、Preview URL，或連已發佈網站也受到影響。
2. 選取一次 Reload App Viewer、在新分頁中開啟 Preview，並測試無痕視窗。
3. 檢查目前的任務或建置是否仍在執行。等待其完成後再重試。
4. 如果明確訊息指出 Cloud & AI 餘額不足或 app 已被停用，請開啟 Settings → Cloud & AI 並檢查該餘額。不要只因為空白畫面就進行儲值。
5. 記錄任何 Console 或 Network 錯誤，但不要分享 cookies、tokens 或機密值。

如果畫面仍然空白，請聯絡 Support，並附上 Chat Link、完整 Viewer URL、時間與時區、受影響環境、螢幕截圖，以及已去識別化的錯誤細節。