部署失敗只看到一大堆英文？三步找出建置紀錄裡真正的錯誤那一行
紅色的一大片，其實只有一行是原因
週四下午，行銷經理小慧把 ChatGPT 協助做好的活動網站丟到部署平台。畫面跳出一個紅色的「Build failed」，底下是幾百行英文。她往下捲了兩分鐘，什麼也沒看懂，只好截圖傳給老闆：「好像壞了，我不知道哪裡壞。」
這個場景在台灣的小公司非常常見。您能走到「按下部署」這一步，代表網站本身已經做出來了，這已經完成了最花力氣的部分。接下來只是學會一個小技巧：建置紀錄是照時間順序寫的流水帳，真正的原因通常只有一兩行，其餘都是陪襯。
實務上可以照三個步驟讀：
- 先看是哪一個步驟失敗。 紀錄通常分段，例如「安裝套件」「建置」「啟動」。紅色出現在哪一段，問題就在那一段。
- 找「第一個」錯誤，不是最後一個。 結尾常見的
exit code 1、Build failed只是結果。原因在它上面，請搜尋error、ERR!、failed、not found、incompatible這幾個字，從最上面的那一筆開始看。 - 只讀錯誤那行前後各約 20 行。 其餘的下載進度、警告（warning）通常可以先忽略。黃色警告不會讓建置失敗，紅色錯誤才會。
三種最常見的錯誤，長什麼樣子
| 紀錄裡看到的關鍵字 | 白話意思 | 下一步可以做的事 |
|---|---|---|
ERESOLVE unable to resolve dependency tree、404 Not Found - package | 套件彼此打架，或指定的套件不存在 | 把這段貼給 AI，請它調整套件版本 |
engine "node" is incompatible、requires Node >= 20 | 專案要求的執行環境版本，和平台預設的不一樣 | 在專案裡指定版本（如 .nvmrc 或 package.json 的 engines 欄位） |
Missing script: "build"、command not found、output directory not found | 平台不知道怎麼建置，或找不到建置完成的資料夾 | 確認建置指令與輸出資料夾名稱（常見是 dist、build、out） |
套件裝不起來，是 AI 生成專案最常見的一類。AI 寫程式時參考的套件版本，和現在能裝的版本常有落差。紀錄裡會直接點名是哪兩個套件衝突，這一整段就是最有價值的線索。
版本不符，常讓人覺得「明明在我電腦上好好的」。您的電腦裝的是某個版本，平台預設的是另一個。紀錄裡通常會寫出「需要哪個版本、目前是哪個版本」，兩個數字對一下就知道。
找不到指令或資料夾，則多半是專案設定和平台期待的不一致。例如網站建置完放在 dist，但平台去找 build。這類錯誤看起來嚇人，修正往往只要改一個設定值。
另外還有一個小細節：紀錄寫 Module not found: Can't resolve './Header'，而您檔案明明存在，常是檔名大小寫不同（header.jsx 與 Header）。Windows 與 macOS 不太計較，部署用的 Linux 伺服器會計較。這是一個很值得先檢查的地方。
如果想把整體上線前的檢查做得更完整，可以搭配這份 AI 寫的程式碼上線檢查清單。
貼給 AI 或工程師，哪一段最有用
兩種常見做法都不理想：只貼最後一行「Build failed」，對方無從判斷；整份幾千行全貼，重點又被淹沒。建議整理成下面這個固定格式：
- 一句背景： 專案怎麼做出來的（例如 Lovable、Cursor 或 ChatGPT）、部署到哪個平台。
- 失敗的步驟名稱： 是安裝、建置還是啟動。
- 第一個錯誤行，加上前後約 20 到 30 行。
- 專案的
package.json（若是 Python 專案，則是requirements.txt）。這個檔案能讓對方看到您用了哪些套件與指令。 - 您已經試過什麼。 這能避免對方重複建議同樣的事。
請 AI 時可以加一句：「請先用白話說明是哪一行造成失敗，再給我最小的修改方式。」這樣得到的答案比較容易照著做，也比較不會被整個改寫專案。
有一件事請務必留意：貼出去之前，先掃一遍有沒有密碼、金鑰、token 之類的字串。紀錄有時會不小心印出環境設定。.env 檔案本身不要貼。
下一步：讓建置紀錄變成看得懂的步驟
如果您手上已經有網站檔案，想先試試能不能跑起來，可以到 /launch/ 上傳 ZIP 或單一 HTML 檔（上限 200 MB）。系統會檢查檔案、解壓縮、判斷專案類型並建置，每一步都看得到進度，需要時也能打開建置紀錄，用上面的方法找出錯誤行。成功後會得到 <名稱>.aionline.tw 的公開網址，免費預覽 7 天，不需信用卡、不會自動扣款。
請先知道它的範圍：免費預覽只支援靜態檔案，也就是 HTML、CSS、JS，或建置後輸出成靜態檔的前端專案。如果您的專案需要常駐的後端或資料庫，系統會提供 AI 健診報告，說明原因與可行方向。
如果您照著上面的步驟讀過、也問過 AI，錯誤仍然卡著，就是請人看一眼的時候了。可以透過 /contact/ 與我們聊聊，範圍與費用都會先以書面談定。
關於 AI 上線專家
AI 上線專家讓您的 AI 幫您把網站部署上線：把一句話貼給 Claude Code、Cursor 或 Codex，幾分鐘後就有一個 您的名稱.aionline.tw 公開網址，可以直接傳給客戶或同事看。
- 免費預覽，不需信用卡，到期自動下線、不會扣款；滿意再升級為永久，最低 NT$99 / 月起
- 靜態網站、Node／Python 等有後端的網站都能部署，需要資料庫時自動配好 Postgres
- 付費方案可以綁自己的網域；部署不起來或需要客製開發，可以直接聯絡我們