建置與預覽疑難排解
當建置失敗或預覽未載入時，請從第一個可見錯誤開始，並依照該症狀的復原路徑逐步處理。本頁涵蓋 App 預覽、Preview、建置錯誤，以及在回報問題前應採取的步驟。
當建置失敗或預覽未載入時，請從第一個可見錯誤開始，並依照該症狀的復原路徑逐步處理。本頁涵蓋 App 預覽、Preview、建置錯誤，以及在回報問題前應採取的步驟。
從這裡開始
在智能體完成任務後，App 預覽會載入你的 app。終端會顯示任務活動與錯誤，而 App 預覽工具列則提供重新載入 App 預覽的控制項、裝置檢視切換、在新分頁中開啟預覽的選項，以及 Console。
- 儲存最新變更，並等待目前的任務或建置完成。
- 如果預覽看起來不是最新狀態，或停留在載入畫面，請選取一次 Reload App Viewer。
- 如果內嵌的 App 預覽卡住或沒有回應，請在新分頁中開啟預覽。
- 開啟 Console 並複製第一個可見錯誤。請保留專案連結與失敗發生的時間。
當建置失敗時
先嘗試 Resolve
當 Atoms 偵測到建置問題時，左下角會出現 問題報告 通知。如果通知中包含 Resolve，請先進行一次修復嘗試，再採取其他動作。
- 選取 Resolve 並等待目前的嘗試完成。
- 執行期間請勿再次選取 Resolve。
- 如果嘗試未完成，請記錄可見狀態，並繼續進行下方的回報步驟。不要再啟動另一個 Resolve 嘗試。
- 嘗試完成後，檢查重新整理後的預覽。如果沒有更新，請重新整理瀏覽器一次。
- 重複造成問題的操作。如果問題仍然存在，請展開 問題報告 並繼續進行下方的回報步驟。
建置錯誤或缺少相依套件
如果 Preview 面板顯示建置錯誤、紅色錯誤橫幅，或缺少套件的訊息，請使用精確訊息來縮小下一步的範圍。
- 開啟 Console 並複製其中可見的完整錯誤訊息。
- 如果有 Resolve 可用，請使用一次並等待嘗試完成。
- 如果沒有 Resolve 按鈕，請將精確錯誤貼到 Project chat，並請智能體修正該建置錯誤。
- 如果錯誤是在某次特定變更後開始出現，請開啟 History，並比較目前版本與上一個可正常運作的版本。
- 如果錯誤難以隔離，請從上一個穩定版本進行 克隆，並逐步重新套用變更。
若錯誤提到 App 預覽、啟動指令碼、Publish、部署記錄，或第三方套件的內部檔案，可能表示這是平台問題。聯絡 Support 時請附上完整錯誤訊息。
建置持續顯示進行中
重試前，先檢查終端中的目前任務活動。如果任務或建置仍在執行，請等待其完成。如果在目前嘗試結束後仍持續顯示進行中，請記錄狀態、時間戳記、專案連結，以及任何可見的錯誤詳細資訊，然後回報問題。
當 Preview 或 App 預覽未載入時
載入畫面或無回應的預覽
請先確認是否只有內嵌的 App 預覽受到影響，或是 Preview URL 與已發佈網站也同樣受到影響。
- 確認目前的任務或建置是否仍在執行。
- 選取一次 Reload App Viewer。
- 在新的瀏覽器分頁中開啟 Preview。
- 在無痕視窗中測試相同的 URL。
- 如果上一個已知可正常運作的版本可以載入，請將其與最近引入問題的變更進行比較。
如果產品明確回報 Cloud & AI 餘額不足或 app 已被停用，請開啟 Settings → Cloud & AI 並檢查該狀態。不要僅因空白畫面就進行儲值。
空白或不完整的預覽
請確認空白畫面是影響整個 app，還是只影響某個頁面或元件。如果只有一個區域受影響，請使用頁面選擇器直接開啟該頁面，並重複最小可重現的使用者流程以到達該處。如果整個預覽都是空白，請回到建置結果，先解決第一個建置或執行階段錯誤，再重新測試。
記錄任何 Console 或 Network 錯誤，但不要分享 cookies、tokens 或機密值。如果問題持續，請在回報中附上已去識別化的錯誤詳細資訊。
Preview 顯示較舊版本
Preview 與已發佈網站是分開的通道。重新整理預覽前，請確認最新變更已儲存，且最新建置已完成。建置完成後重新開啟 Preview。如果仍顯示較舊內容，請在 History 中比較目前版本與上一個已知可正常運作的版本。
當預覽看起來不正確時
互動或導覽無法運作
頁面能渲染，不代表頁面能正常運作。請開啟每個重要的導覽連結、按下主要按鈕、提交關鍵表單，並從頭到尾走完主要使用者流程。當某個互動失敗時，請記錄預期結果停止發生的確切操作，並在每次修正後再次測試該路徑。
行動版版面配置損壞
- 使用 App 預覽工具列中的裝置切換，切換到行動版檢視。
- 可用時，在 Design mode 中選取損壞的元素。
- 描述預期的行動版版面配置，以及哪些內容不得變更。
- 套用一項變更後，驗證桌面版與行動版檢視，以及載入、空狀態、hover 與錯誤狀態。
圖片或其他資產遺失
- 開啟 Files 區段並確認被參照的檔案存在。
- 檢查路徑、檔名與格式是否與 app 使用的參照一致。
- 如果資產最近被移動或重新命名，請還原參照或刻意更新它。
- 選取 Reload App Viewer，然後再次測試受影響的頁面。
智能體修改了錯誤的元素，或破壞了其他區域
- 開啟 History，並從上一個穩定版本進行 克隆。
- 可用時，使用 Design mode 來鎖定精確元素。
- 說明哪些內容不得變更，並且每個提示詞只進行一項變更。
- 在繼續下一項變更前，先驗證結果。
回報問題
當 Resolve 無法使用、問題在完成 Resolve 嘗試後仍然存在、Preview 沒有回應但 Project chat 仍可運作，或智能體調查後仍持續出現非預期行為時，請回報問題。
從 Project chat 開啟 Feedback
- 開啟受影響的 Project chat，並找到最新的相關智能體訊息。
- 選取 ...（更多選項），然後選取 Feedback。
- 在支援訊息工具中，選取 Send us a message，若已存在對話，請在該既有對話中送出回報。
完整的問題報告流程請參閱 回報問題。
提供足夠的細節以重現問題
- 問題摘要。 用一到兩句話描述問題。
- 專案或聊天連結。 附上問題發生處的 URL。
- 日期與時間。 請包含你的時區。
- 重現步驟。 依序列出精確操作。
- 預期結果與實際結果。 說明原本應該發生什麼，以及實際上發生了什麼。
- 你已經嘗試過的內容。 說明是否出現 Resolve、它完成後發生了什麼，以及重新整理或克隆是否改變了結果。
- 瀏覽器與裝置。 請包含瀏覽器、作業系統與裝置類型。
- 佐證資料。 附上螢幕截圖或錄影，以及相關且可見的問題報告或 Console 詳細資訊。
分享螢幕截圖或日誌前，請移除密碼、API 金鑰、驗證 tokens、cookies、付款詳細資訊，以及不相關的個人或機密資料。
問題修正後
從頭到尾執行主要使用者流程。檢查桌面版與行動版檢視中的 Preview，從頁面選擇器開啟每個頁面，並確認 Console 中沒有紅色錯誤訊息。如果 app 已準備好發佈，請替換任何佔位內容，並在 App 預覽中完成發佈檢查。