GitHub Pages

GitHub Pages 404 錯誤完整解決指南：10 種常見原因與修復方法

2025-12-15 19 分鐘閱讀 VibeFix

GitHub Pages 404 錯誤完整解決指南：10 種常見原因與修復方法

辛苦把網站推上 GitHub Pages，結果打開網址只看到冷冰冰的 404 錯誤頁面？這大概是每個用過 GitHub Pages 的人都遇過的問題。別擔心，這篇文章會帶你一步步找出問題所在。

404 錯誤的原因其實不複雜，但種類很多。從最基本的 Repository 設定問題，到框架的路由配置錯誤，每一種都有對應的解法。這篇文章整理了 10 種最常見的原因，幫你快速定位問題並修復。

GitHub Pages 404 錯誤的運作原理

在開始排查之前，先了解一下 GitHub Pages 的 404 錯誤是怎麼產生的。

GitHub Pages 的路由邏輯

當訪客輸入網址時，GitHub Pages 會這樣處理：

  1. 先找對應路徑的檔案，例如 /about 會找 /about.html 或 /about/index.html
  2. 如果找不到，就回傳 404 錯誤
  3. 如果 Repository 根目錄有 404.html，就顯示這個自訂錯誤頁面
github-pages-routing-logic-flow

靜態網站 vs SPA 的差異

這裡有個重要觀念要先搞清楚：

傳統靜態網站：每個頁面都有對應的 HTML 檔案
- /about → 需要 about.html 或 about/index.html
- /contact → 需要 contact.html 或 contact/index.html

SPA（單頁應用程式）：只有一個 index.html，靠 JavaScript 處理路由
- React Router、Vue Router 這類工具會在瀏覽器端處理路由
- 但 GitHub Pages 不知道這件事，所以直接存取子路徑會 404

了解這個差異，很多 404 問題就容易理解了。

原因 1-3：Repository 設定問題

最常見的 404 錯誤，往往出在最基本的 Repository 設定上。

原因 1：Repository 名稱設定錯誤

如果你想建立 User Site（username.github.io 格式的網址），Repository 名稱必須完全正確。

正確格式：
- Repository 名稱必須是 username.github.io
- username 要換成你的 GitHub 帳號名稱（注意大小寫）

常見錯誤：
- 名稱打錯字：usernmae.github.io
- 大小寫不對：Username.github.io（如果帳號是小寫）
- 多加空格或符號

修復方式：
到 Repository 的 Settings → General → Repository name，確認名稱正確。

原因 2：GitHub Pages 功能沒有啟用

即使 Repository 名稱正確，你還是要手動啟用 Pages 功能。

檢查方式：
1. 進入 Repository → Settings → Pages
2. 確認「Source」有選擇分支（不是 None）
3. 確認看到綠色的成功訊息和網址

如果沒有啟用：
1. 在「Source」選擇 main 或 gh-pages 分支
2. 選擇資料夾（/(root) 或 /docs）
3. 點擊「Save」

原因 3：發布來源設定錯誤

GitHub Pages 可以從不同地方發布網站：

  • main 分支的根目錄
  • main 分支的 /docs 資料夾
  • gh-pages 分支

常見問題：
- 設定發布 main 分支，但檔案放在 gh-pages 分支
- 設定發布 /docs 資料夾，但資料夾不存在

修復方式：
確認你的網站檔案放在哪裡，然後到 Settings → Pages 選擇對應的來源。

原因 4-6：檔案與路徑問題

Repository 設定沒問題，接下來看檔案本身。

原因 4：index.html 檔案缺失

GitHub Pages 需要一個入口檔案。如果根目錄沒有 index.html，首頁就會 404。

檢查方式：
1. 確認 Repository 根目錄（或設定的發布資料夾）有 index.html
2. 注意檔案名稱必須是小寫的 index.html，不是 Index.html

修復方式：

# 確認檔案存在
ls -la
# 應該要看到 index.html

如果你用框架，確認 build 之後有產生 index.html。

原因 5：檔案名稱大小寫問題

這是很多人會忽略的問題：GitHub Pages 區分大小寫。

常見情況：
- 本地電腦是 Windows 或 macOS，不區分大小寫
- 你把 About.html 改成 about.html
- Git 可能沒有追蹤到這個改變
- 結果 GitHub 上還是 About.html，但你連結寫的是 /about

檢查方式：
直接到 GitHub Repository 頁面看檔案名稱，不要只看本地電腦。

修復方式：

# 強制 Git 重新追蹤檔案
git mv About.html about.html
git commit -m "Fix filename case"
git push

原因 6：相對路徑設定錯誤

如果你的網站是 Project Site（網址是 username.github.io/repo-name），相對路徑就會出問題。

github-pages-relative-path-comparison

原因 7-8：分支與部署問題

設定和檔案都沒問題，那問題可能在部署過程。

原因 7：部署到錯誤的分支

有時候你以為已經部署了，但其實推到了錯誤的分支。

常見情況：
- 程式碼在 main 分支，但 Pages 設定發布 gh-pages 分支
- 用 GitHub Actions 部署到 gh-pages，但分支是空的

檢查方式：
1. 確認 Settings → Pages 的「Source」設定
2. 切換到對應的分支，確認檔案存在

修復方式：
要嘛修改 Pages 設定，要嘛確保檔案部署到正確的分支。

原因 8：Build 失敗但沒注意到

如果你用 GitHub Actions 或 Jekyll，build 過程可能失敗了，但你沒有注意到。

檢查方式：
1. 到 Repository 的 Actions 頁面
2. 看最近的 workflow 執行結果
3. 如果是紅色 X，點進去看錯誤訊息

常見的 build 錯誤：
- Node.js 版本不對
- 套件安裝失敗
- Build 指令有錯誤
- 環境變數沒設定

修復方式：
根據錯誤訊息修復問題，然後重新推送程式碼觸發部署。

原因 9-10：SPA 與框架特定問題

如果你用 React、Vue、Angular 等框架，404 問題通常出在路由設定。

spa-router-404-error-visual

原因 9：SPA 路由問題

SPA 用的是前端路由（React Router、Vue Router），但 GitHub Pages 不認識這些路由。

問題說明：
1. 使用者在首頁點連結到 /about
2. React Router 處理，畫面正常顯示
3. 使用者重新整理頁面或直接輸入 /about
4. GitHub Pages 找不到 about.html，回傳 404

解決方式 1：使用 HashRouter

// React
import { HashRouter } from 'react-router-dom';

// 網址會變成 username.github.io/#/about
<HashRouter>
  <App />
</HashRouter>

解決方式 2：建立 404.html 重定向

<!-- 404.html -->
<!DOCTYPE html>
<html>
<head>
  <script>
    // 把路徑轉成 query string，重定向到首頁
    var path = window.location.pathname;
    window.location.href = '/?p=' + path;
  </script>
</head>
</html>

然後在 index.html 加入對應的處理邏輯。

原因 10：Base Path 設定錯誤

如果是 Project Site，框架需要知道網站不是放在根目錄。

React (Create React App)：

// package.json
{
  "homepage": "https://username.github.io/repo-name"
}

React (Vite)：

// vite.config.js
export default {
  base: '/repo-name/'
}

Vue：

// vue.config.js
module.exports = {
  publicPath: '/repo-name/'
}

Angular：

ng build --base-href=/repo-name/

想了解更多框架部署細節？請參考 React/Vue 框架部署完整教學。

SPA 路由問題很複雜？VibeFix 幫你快速解決框架部署的 404 錯誤

前端框架的部署設定牽涉到很多細節，一個設定錯誤就會導致整個網站出問題。如果你試了很多方法還是搞不定，讓 VibeFix 的專家來幫你。

立即預約諮詢 →

404.html 自訂錯誤頁面設定

與其讓使用者看到醜醜的預設 404 頁面，不如自己做一個。

建立自訂 404 頁面

在 Repository 根目錄建立 404.html：

<!DOCTYPE html>
<html lang="zh-TW">
<head>
  <meta charset="UTF-8">
  <title>找不到頁面 - 我的網站</title>
  <style>
    body {
      font-family: sans-serif;
      display: flex;
      justify-content: center;
      align-items: center;
      height: 100vh;
      margin: 0;
    }
    .container {
      text-align: center;
    }
    h1 { font-size: 6rem; margin: 0; }
    p { font-size: 1.5rem; color: #666; }
    a { color: #0066cc; }
  </style>
</head>
<body>
  <div class="container">
    <h1>404</h1>
    <p>找不到你要的頁面</p>
    <a href="/">回到首頁</a>
  </div>
</body>
</html>

SPA Fallback 技巧

如果你想讓 SPA 的路由正常運作，可以用 404.html 做 fallback：

<!-- 404.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script>
    // 儲存當前路徑到 sessionStorage
    sessionStorage.redirect = location.href;
  </script>
  <meta http-equiv="refresh" content="0;URL='/'">
</head>
</html>

然後在 index.html 的 <script> 裡面加入：

(function(){
  var redirect = sessionStorage.redirect;
  delete sessionStorage.redirect;
  if (redirect && redirect !== location.href) {
    history.replaceState(null, null, redirect);
  }
})();

這樣使用者存取子路徑時，會先被重定向到首頁，然後前端路由再接手處理。

系統性除錯流程：按步驟排查

當 404 發生時，跟著這個流程排查，可以更有效率地找到問題。

github-pages-debug-checklist

除錯檢查清單

按照這個順序檢查：

第一步：確認 Repository 設定
- [ ] Repository 名稱正確（User Site 要是 username.github.io）
- [ ] Repository 是 Public（或你有 GitHub Pro）

第二步：確認 Pages 設定
- [ ] Settings → Pages 有啟用
- [ ] Source 選擇了正確的分支
- [ ] 如果選 /docs，確認資料夾存在

第三步：確認檔案
- [ ] 發布位置有 index.html
- [ ] 檔案名稱大小寫正確
- [ ] 沒有語法錯誤（HTML、CSS、JS）

第四步：確認部署
- [ ] Actions 執行成功（如果有用 GitHub Actions）
- [ ] 最後一次 commit 已經推送
- [ ] 等待 1-5 分鐘讓部署完成

第五步：確認路徑
- [ ] 連結使用正確的相對路徑
- [ ] 框架的 base path 設定正確
- [ ] 圖片、CSS 等資源路徑正確

Chrome DevTools 技巧

開啟 DevTools（按 F12）來幫助除錯：

Console 頁籤：
- 查看 JavaScript 錯誤
- 確認沒有 404 資源載入失敗

Network 頁籤：
- 看 HTTP 狀態碼
- 找出哪些檔案 404
- 確認檔案實際請求的路徑

Application 頁籤：
- 清除快取（Cache → Clear site data）
- 有時候是瀏覽器快取造成的假象

常用檢查指令

# 確認本地和遠端分支同步
git status

# 查看遠端 Repository 的分支
git branch -r

# 強制重新部署（觸發 GitHub Actions）
git commit --allow-empty -m "Trigger rebuild"
git push

試過以上方法還是 404？讓專家幫你檢查

聯繫 VibeFix →

總結與延伸閱讀

GitHub Pages 的 404 錯誤雖然惱人，但只要系統性地排查，都能找到原因並解決。

重點回顧

  1. 基本設定：確認 Repository 名稱、Pages 啟用、發布來源
  2. 檔案問題：確認 index.html 存在、檔案名稱大小寫正確
  3. 路徑問題：Project Site 要注意相對路徑和 base path
  4. SPA 問題：前端路由需要額外處理，考慮 HashRouter 或 404 fallback
  5. 部署問題：檢查 GitHub Actions 執行結果

延伸閱讀

GitHub Pages 404 問題解決不了？VibeFix 幫你搞定

不管是設定問題、路徑問題，還是框架的路由設定，VibeFix 的專家都能幫你快速找出原因並修復。我們處理過各種複雜的部署問題，讓你的網站順利上線。

立即預約諮詢 →

FAQ

為什麼我的 GitHub Pages 顯示 404？

GitHub Pages 顯示 404 最常見的原因包括：Repository 名稱設定錯誤（User Site 必須是 username.github.io）、Pages 功能沒有啟用、發布來源選錯分支、根目錄缺少 index.html 檔案、檔案名稱大小寫問題，以及使用 SPA 框架但沒有正確設定路由。建議按照本文的除錯清單逐步檢查。

React/Vue SPA 在 GitHub Pages 為什麼會 404？

這是因為 SPA（單頁應用程式）使用前端路由（React Router、Vue Router），但 GitHub Pages 只認實際存在的 HTML 檔案。當使用者直接存取子路徑（如 /about）或重新整理頁面時，GitHub Pages 找不到 about.html 就會回傳 404。解決方式包括：使用 HashRouter（網址會有 #）、建立 404.html 做重定向，或使用其他支援 SPA 的託管服務如 Vercel、Netlify。

如何自訂 GitHub Pages 的 404 頁面？

在 Repository 根目錄（或設定的發布資料夾）建立一個 404.html 檔案即可。GitHub Pages 會自動使用這個檔案作為 404 錯誤頁面。你可以在這個頁面放入自己的設計、導覽連結，甚至是 SPA 的重定向邏輯。記得檔案名稱必須是小寫的 404.html。

github pages 404 github pages 404 error github pages not found github pages 錯誤
分享文章：
V

VibeFix

專門解決 AI Vibe Coding 後的疑難雜症，讓你的專案順利上線。

這篇文章有幫到你嗎？

如果還有問題，讓我們直接幫你解決！

聯繫我們