如何修正網頁 App 出現的空白白頁

空白白頁幾乎總是代表兩種情況之一：App 的 JavaScript 在繪製任何東西之前就當機了，或是 JavaScript 根本沒有載入。請開啟瀏覽器主控台（右鍵 → 檢查 → Console），閱讀第一則紅色錯誤，然後檢查 Network 分頁中載入失敗的檔案。大多數原因是缺少環境變數、基礎路徑錯誤、建置未完成，或是某個元件當機。

本指南涵蓋以 React、Vue 或類似框架建置的單頁應用程式（包括 AI 建置工具製作的 App），這類 App 最常出現空白頁面。

為什麼頁面是白的

現代的單頁應用程式（SPA）會傳送給瀏覽器一個幾乎是空的 HTML 檔案，大致如下：

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

接著 JavaScript 會在那個空的 div 中建置整個頁面。如果腳本載入失敗，或在渲染之前就拋出錯誤，div 就會保持空白，你看到的就是白色。這個頁面並不是以可見的方式「壞掉」，它只是從來沒有被繪製出來。

因此，修正工作總是從開發者工具開始，而不是從頁面本身開始。

步驟一：閱讀主控台

開啟開發者工具：在頁面上按右鍵並選擇檢查，或按 F12（Mac 上為 Cmd+Option+I）。切換到 Console（主控台）分頁，然後重新載入頁面。

請看第一則紅色錯誤；後面的錯誤通常只是附帶影響。錯誤的內容會指出原因：

請複製完整的錯誤文字，包括檔名與行號。如果你使用的是 AI 建置工具，直接把它貼到對話中。

步驟二：檢查檔案是否載入成功

開啟 Network 分頁，勾選 Disable cache（停用快取），然後重新載入。查看 .js 與 .css 檔案的請求。

• JavaScript 檔案的狀態為 404：頁面正在請求伺服器上不存在的檔案。
• 狀態為 200，但類型是 text/html：伺服器回傳了一個頁面（通常是 index.html 本身，因為 SPA 後備規則），而不是腳本。根本原因相同：檔案不在頁面預期的位置。

常見原因：

基礎路徑錯誤。 如果 App 是由子資料夾提供，例如 example.com/app/，但建置時卻設定為從 /assets/... 載入檔案，那麼每個腳本請求都會找不到。在 Vite 中，這是 vite.config 中的 base 選項；在 Create React App 中是 homepage 欄位；在 Next.js 中是 basePath。它必須與 App 實際提供服務的位置相符。

過時的 index.html。 建置工具會為檔案加上內容雜湊的名稱，例如 index-a1b2c3.js。新的部署之後，舊檔案就不見了。如果瀏覽器或 CDN 仍快取著舊的 index.html，它就會請求舊檔案而拿不到任何東西。強制重新整理（Cmd+Shift+R 或 Ctrl+Shift+R）可以確認這一點。長期的解決方法是：為 index.html 提供短時效或不快取的標頭，而帶有雜湊的檔案則長期快取。

建置未完成或未部署。 如果建置失敗，主機可能提供的是舊的或空的輸出資料夾。請查看建置記錄中的錯誤。

發佈了錯誤的資料夾。 主機必須提供建置輸出（通常是 dist 或 build），而不是專案的原始碼資料夾。若提供原始碼，得到的 index.html 會指向 /src/main.tsx，而瀏覽器無法執行它。

步驟三：檢查環境變數

前端 App 通常會在建置時讀取 API 網址或公開金鑰等設定。如果正式環境的建置缺少某個變數，像 createClient(undefined, undefined) 這樣的程式碼會立即拋出錯誤，頁面就會變成白色。

需要知道的事項：

• 在 Vite 中，只有以 VITE_ 開頭的變數可以在瀏覽器程式碼中使用，讀取方式為 import.meta.env.VITE_NAME。在 Create React App 中是 REACT_APP_；在 Next.js 中是 NEXT_PUBLIC_。
• 這些值是在 App 建置時就寫入的。在建置之後才新增變數，必須重新建置並重新部署才會生效。
• 預覽環境或你的本機可能有一個 .env 檔案，但正式環境的建置並沒有。請在主機上設定相同的變數。
• 帶有上述前綴的任何東西，最後都會進入公開的 JavaScript。只放公開的值，絕不要放密鑰。

快速測試方法：在主控台錯誤中搜尋設定名稱附近的 undefined，或直接詢問：

已發佈的 App 顯示空白頁。請列出前端讀取的每一個環境變數，檢查正式環境的建置中哪些缺少或為空，並在缺少時讓 App 顯示清楚的錯誤訊息，而不是空白頁。

步驟四：修正當機

如果主控台顯示一般的 JavaScript 錯誤，代表程式碼在渲染時當機了。AI 建置的 App 中典型的原因包括：

• 資料尚未載入。 元件在 user 抵達之前就讀取 user.name。解決方法是加入載入狀態，或使用可選串連（user?.name）。
• 資料為空。 新帳號沒有任何記錄，但程式碼假設列表至少有一個項目。
• 資料格式非預期。 API 回傳了錯誤物件，而不是程式碼預期的列表。
• 缺少匯入。 檔案被重新命名或移動之後。
• 在伺服器端渲染時使用只存在於瀏覽器的 API，例如在 Next.js 伺服器元件中使用 window 或 localStorage。

把完整錯誤、頁面，以及你當時登入的是哪個帳號，一併提供給 AI：

新使用者的 Dashboard 頁面是空白的。主控台：TypeError: Cannot read properties of undefined (reading 'map')，位於 ProjectList.tsx:18。我的帳號有專案，所以是正常的。請修正它，讓空帳號顯示「尚無專案」，並在預覽中測試一個新帳號。

步驟五：加入錯誤邊界

在 React 中，一個當機的元件可能讓整個 App 被卸載，這就是為什麼一個小小的錯誤會產生完全空白的頁面。錯誤邊界是一個元件，會攔截其下方的渲染錯誤，並改為顯示備用畫面。

在主要路由外圍加入錯誤邊界，顯示「發生錯誤」訊息與一個重新載入按鈕，並把錯誤記錄到主控台。讓標頭與導覽列位於它的外部，這樣它們仍然能夠渲染。

它不會修正錯誤本身，但訪客會看到一則訊息，而不是空白畫面，你也能看出是哪裡壞掉了。

步驟六：沒有錯誤，但仍是空白

如果主控台沒有錯誤，腳本也都有載入：

• 檢查 Elements 分頁。 <div id="root"> 裡面有內容嗎？如果有，代表它有渲染但看不到：白字配白底、opacity: 0、display: none，或是有一個全螢幕元素把它蓋住了。
• 檢查路由器。 如果沒有任何路由符合目前的網址，而且也沒有「找不到」路由，有些路由器就會什麼都不渲染。請加入一個顯示 404 頁面的萬用路由。
• 檢查掛載點。 程式碼必須掛載到一個確實存在的元素上。如果 index.html 有 id="app"，而程式碼卻去尋找 root，就什麼都不會出現（而 React 通常會記錄一則錯誤）。
• 檢查瀏覽器擴充功能。 試試無痕視窗。廣告攔截器偶爾會阻擋名稱類似 analytics 或 ads 的腳本。

只有在重新整理頁面後才變成空白？

如果首頁正常，但重新整理 /dashboard 後出現空白頁或 404，代表伺服器不知道要為 App 路由回傳 index.html。這是路由後備規則的問題，請參考如何修正部署後的 404 錯誤。

常見錯誤

• 只讀最後一則錯誤，而不是第一則。 第一行紅色錯誤通常就是原因。
• 設定環境變數後沒有重新建置。 前端的變數是在建置時就固定的。
• 只用自己的帳號測試。 空帳號導致的當機，是最常見的空白頁原因之一。
• 假設部署成功。 在除錯程式碼之前，先檢查建置記錄。
• 把一切都怪到瀏覽器快取。 強制重新整理幾秒鐘就能排除這個可能；如果頁面仍然空白，問題出在別處。

Mythex 中的空白頁

如果預覽是空白的，請先確認 App 正在執行（開啟 Code → terminal），然後請 Mythex 啟動正確的伺服器、按下預覽工具列中的 Refresh（重新整理），或使用 /fix。如果是已發佈網址空白，文件建議等待一分鐘後強制重新整理，確認在發佈前已設定好環境變數與資料庫，並檢查你的主機配額。請記住，已發佈的 App 是一個快照：修正後請重新發佈。如果是某次修改造成的，可在最後一則正常的回覆上使用 Revert to this point（回復到此時點），將專案回復到該狀態。請參考文件中的疑難排解與發佈疑難排解，也可以參考我們的一般指南除錯 AI 建置的 App。

空白頁檢查清單

• 已閱讀主控台中的第一則紅色錯誤
• 已檢查 Network 分頁中回傳 404 或 HTML 的 .js／.css 檔案
• 基礎路徑與 App 的提供位置相符
• 建置已完成，且發佈的是建置輸出資料夾
• 所有前端環境變數都已在正式環境的建置中設定，並已重新建置
• 已修正當機，包括空帳號與新帳號的情況
• 已加入錯誤邊界，讓未來的當機會顯示訊息
• 已為未知網址加入萬用路由
• 已在強制重新整理與無痕視窗中測試

常見問題