如何修復網頁應用程式的空白頁面

空白頁面幾乎總是代表以下兩種情況之一：應用程式的 JavaScript 在繪製任何東西之前就已崩潰，或者 JavaScript 根本沒有載入。開啟瀏覽器主控台（按右鍵 → 檢查 → Console），閱讀第一個紅色錯誤，然後查看 Network 分頁中載入失敗的檔案。大部分成因是環境變數缺失、基礎路徑錯誤、建構未有完成，或某個元件崩潰。

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

為什麼頁面是白的

現代的單頁應用程式（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 回退），而不是腳本。根本原因相同：檔案不在頁面預期的位置。

常見原因：

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

**過時的 index.html。**建構工具會為檔案加上內容雜湊的名稱，例如 index-a1b2c3.js。新部署之後，舊檔案就不存在了。如果瀏覽器或 CDN 仍快取著舊的 index.html，它就會要求舊檔案，卻得不到任何東西。強制重新整理（Cmd+Shift+R 或 Ctrl+Shift+R）可以確認這一點。長遠的修復方法，是讓 index.html 使用短時間或不快取的標頭，而帶雜湊的檔案則可以長時間快取。

**建構未完成，或未有部署。**如果建構失敗，主機可能正在提供舊的或空的輸出資料夾。請檢查建構記錄中的錯誤。

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

第三步：檢查環境變數

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

需要注意的事項：

• 在 Vite 中，只有以 VITE_ 為前綴的變數可在瀏覽器代碼中使用，並以 import.meta.env.VITE_NAME 讀取。在 Create React App 中前綴是 REACT_APP_；在 Next.js 中則是 NEXT_PUBLIC_。
• 這些值會在應用程式建構時被嵌入。在建構之後才新增變數，要重新建構並重新部署，才會生效。
• 本機或預覽環境可能有正式建構沒有的 .env 檔案。請在主機上設定相同的變數。
• 帶有這些前綴的內容最終都會進入公開的 JavaScript。只放公開的值，絕不要放密鑰。

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

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

第四步：修復崩潰

如果主控台顯示一般的 JavaScript 錯誤，代表代碼在渲染時崩潰。AI 建構應用程式中典型的成因包括：

• 資料尚未載入。 元件在 user 抵達之前就讀取 user.name。修復方法是加入載入狀態，或使用可選鏈（user?.name）。
• 資料為空。 新帳戶沒有任何記錄，而代碼假設列表至少有一個項目。
• 資料結構與預期不符。 API 回傳了一個錯誤物件，而不是代碼預期的列表。
• 缺少導入。 檔案被改名或移動之後，導入沒有一併更新。
• 在伺服器端渲染時使用只限瀏覽器的 API，例如在 Next.js 伺服器元件中使用 window 或 localStorage。

把完整的錯誤、頁面，以及你當時登入的是哪個帳戶，一併告訴 AI：

新用戶的儀表板頁面是空白的。主控台：TypeError: Cannot read properties of undefined (reading 'map')，位於 ProjectList.tsx:18。我的帳戶有專案，所以它對我來說是正常的。請修復，讓沒有任何資料的帳戶顯示「尚無專案」，並在預覽中測試一個新帳戶。

第五步：加入錯誤邊界

在 React 中，一個崩潰的元件可能會把整個應用程式卸載，所以一個小小的錯誤就會令頁面完全空白。錯誤邊界是一個元件，它會捕捉其下方的渲染錯誤，並改為顯示後備內容。

在主要路由外圍加入錯誤邊界，顯示「發生錯誤」並附有重新載入按鈕，同時把錯誤記錄到主控台。讓標題列和導覽列位於邊界之外，這樣它們仍會正常渲染。

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

第六步：沒有錯誤，但仍然空白

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

• 檢查 Elements 分頁。 <div id="root"> 之中有沒有內容？如果有，代表它已渲染，只是看不見：白色文字配白色背景、opacity: 0、display: none，或是一個全螢幕元素把它遮住了。
• 檢查路由器。 如果沒有路由符合目前的網址，而且也沒有「找不到頁面」路由，某些路由器會什麼都不渲染。請加入一條通配路由，顯示 404 頁面。
• 檢查掛載點。 代碼必須掛載到一個確實存在的元素。如果 index.html 中的元素是 id="app"，而代碼卻尋找 root，那就什麼都不會出現（React 通常會記錄一個錯誤）。
• 檢查瀏覽器擴充功能。 試試私密視窗。廣告封鎖工具偶爾會封鎖名稱中含有 analytics 或 ads 的腳本。

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

如果首頁正常，但重新整理 /dashboard 時卻顯示空白頁面或 404，代表伺服器不知道要為應用程式的路由回傳 index.html。這是路由回退的問題，已在如何修復部署後的 404 錯誤中說明。

常見錯誤

• **閱讀最後一個錯誤，而不是第一個。**第一行紅色文字通常就是成因。
• **設定環境變數後沒有重新建構。**前端變數在建構時就已固定。
• **只用自己的帳戶測試。**空帳戶崩潰是最常見的空白頁面成因之一。
• **假設部署成功。**在除錯代碼之前，先檢查建構記錄。
• **把一切都歸咎於瀏覽器快取。**強制重新整理幾秒鐘便能排除這個可能；如果頁面仍然空白，問題就在別處。

Mythex 中的空白頁面

如果 預覽 是空白的，請先確認應用程式正在運行（開啟 Code → terminal），然後要求 Mythex 啟動正確的伺服器、在預覽工具列中點擊 Refresh，或使用 /fix。如果是已發佈網址空白，文件建議等待一分鐘後強制重新整理，確認在發佈前已設定環境變數和資料庫，並檢查你的託管配額。請緊記，已發佈的應用程式是一個快照：修復之後要重新發佈。如果是某次更改造成的，對最後一個正常的回覆按 還原到此時點，即可把專案回復到之前的狀態。請參閱文件中的疑難排解和發佈疑難排解，以及我們的通用指南除錯 AI 建構應用程式。

空白頁面檢查清單

• 已閱讀主控台中第一個紅色錯誤
• 已在網絡分頁中檢查出現 404 或回傳 HTML 的 .js/.css 檔案
• 基礎路徑與應用程式的提供位置相符
• 建構已完成，且發佈的是建構輸出資料夾
• 正式建構中已設定所有前端環境變數，並已重新建構
• 崩潰已修復，包括空帳戶和新帳戶的情況
• 已加入錯誤邊界，以便日後的崩潰會顯示訊息
• 已為未知網址加入通配路由
• 已在強制重新整理並使用私密視窗之後測試

常見問題