部署失敗排除
版本失敗時,先在版本頁看原因。內容被拒收就修正後重新上傳;平台出錯就直接重試。
內容被拒收#
| 你看到的 | 原因 | 怎麼修 |
|---|---|---|
| 無法判斷如何建置這份原始碼 | zip 最上層沒有 package.json、index.html 或 Dockerfile。 | 從專案資料夾裡面壓縮,或見從原始碼部署。 |
| 專案是服務,但上傳的內容被當成一般檔案 | zip 最上層沒有 Dockerfile 或設定檔(package.json、go.mod、pyproject.toml、requirements.txt、setup.py):程式在子資料夾裡,例如 backend/。 | 到「設定 › 建置設定」把根目錄 Root Directory 設成那個資料夾,再部署一次。失敗訊息會列出可能的資料夾。 |
找不到 index.html | 壓縮的是資料夾本身,不是資料夾裡的內容。 | 進到資料夾裡再壓縮,讓 index.html 在最上層。 |
| 檔案裡有密鑰 | 上傳的內容裡有像 API 金鑰或權杖的字串。 | 從檔案移除,換一把新的金鑰,改在專案的「設定」輸入,再重新上傳。 |
映像檔沒有 CMD | Dockerfile 沒有啟動指令。 | 加上 CMD 或 ENTRYPOINT。 |
USER 不存在 | Dockerfile 指定了映像檔裡沒有的使用者。 | 改用數字 uid,或映像檔裡已有的使用者,例如 node。 |
| 嚴重漏洞 | 映像檔裡的套件有已知的嚴重漏洞。 | 把套件升級到掃描結果寫的修正版本,或換成已包含該版本的新基底映像檔。 |
建置執行了但失敗#
失敗代碼是 buildFailed:建置開始了,但其中一個步驟失敗。失敗資訊會顯示失敗的步驟、它印出的內容,以及它結束時的 exit code。在主控台,看版本頁失敗訊息裡的記錄摘錄;透過 MCP,看 sites_deploy_status 的 failure.buildLog。
| Exit code | 原因 | 怎麼修 |
|---|---|---|
| 127 | 建置執行了一個沒有安裝的指令。例如建置會執行 tsc,但 package.json 的 dependencies 和 devDependencies 都沒有 typescript。 | 加上那個套件,或從建置指令拿掉這個指令。 |
修正專案後再部署一次,也就是重新上傳:重試同一個版本只會以同樣的方式再失敗一次。
版本預覽網址沒有回應#
- 網頁(靜態網站):版本發佈之前,它的預覽網址會回
404site not found。 - 服務:從未上線過的版本不會啟動,所以在它上線之前,預覽網址會回
502service unavailable,並帶標頭X-Sites-Refusal: relay-unavailable。這不是建置失敗。
上線後請馬上打開對外網址確認。如果不正常,修正後再部署一次。想在訪客遇到之前就發現問題,可以先在另一個環境(例如 staging)試過版本。
等待確認#
有檢查項目設成「會先問過你」並且找到問題時,版本會停在「等待確認」。看過掃描結果後,你可以決定照樣發佈。高風險漏洞就屬於這一類,修法和嚴重漏洞相同,升級之後提示才會消失。
版本一直沒有就緒#
建置成功、也上線了,但「執行」分頁的執行個體一直沒有就緒,多半是通訊埠的問題:伺服器沒有監聽平台給的通訊埠。
- 看版本頁有沒有
imagePortsAmbiguous提示。 - 讓伺服器監聽環境變數
PORT,或到「設定 › 執行設定 › 通訊埠」填伺服器實際監聽的通訊埠。 - 按「重新啟動服務」。
啟動後不斷重新啟動#
最常見的原因是程式寫入了 /tmp 以外的路徑,而檔案系統是唯讀的。把寫入位置改到 /tmp,見容器執行合約。
請求回 504,或串流中途停住#
504 帶著 X-AgentLab-Error: platform-timeout,或串流回應每次都在同樣的秒數停住,就是請求碰到了專案的請求最長時間。把時限調長,也不要讓程式自動重送;見請求最長時間。
平台出錯#
失敗原因是平台本身時,不需要修改內容,也不用重新上傳,直接重試同一個版本。
一小時內沒有建置機器接手的版本,會自動在原本的位置重新排隊一次;再過一小時仍沒有接手,才會顯示已過期。在上傳後一天內可以用同樣方式重試;超過一天就要重新上傳。
如果版本是誤送的,或不想等它,趁它還在排隊時取消,見取消排隊中的建置。
還是找不到原因#
- 到「執行」分頁看執行個體的狀態和最近的記錄。
- 到版本頁看平台留下的提示。
- 請已連接 Agent Lab MCP 的 AI 工具讀部署狀態幫你判斷。它讀到的失敗原因和這一頁的代碼相同。