GitHub Pages 部署框架網站完整指南：React、Vue、Angular、Hugo 實戰教學

用 React、Vue 或其他框架寫好的網站，想部署到 GitHub Pages 卻一直失敗？你不是第一個遇到這個問題的人。框架網站的部署比純 HTML 複雜很多，需要處理 build 設定、路徑配置、還有各種框架特定的眉角。

這篇文章會逐一講解 React、Vue、Angular、Hugo、Next.js 的 GitHub Pages 部署方式。每個框架都有實際可用的設定範例，照著做就能順利部署。如果你已經卡在某個框架的部署問題，直接跳到對應的章節看解法。

框架網站部署 GitHub Pages 的挑戰

在開始之前，先了解為什麼框架部署會比較麻煩。

靜態 vs 動態：GitHub Pages 的限制

GitHub Pages 只支援靜態網站，也就是說它只能託管 HTML、CSS、JavaScript 這些檔案。但大多數框架在開發時是「動態」的：

• React、Vue 需要 Node.js 環境執行 npm start
• Next.js 預設是 Server-side Rendering
• Angular 需要 ng serve 才能跑

所以要部署到 GitHub Pages，必須先把框架專案「build」成純靜態檔案。

Build 輸出的設定

每個框架 build 出來的檔案會放在不同的資料夾：

你需要確保 GitHub Pages 發布的是這些資料夾的內容。

Base Path：最容易出錯的設定

React (Create React App / Vite) 部署教學

React 是最多人用的前端框架，部署方式會根據你用的工具（CRA 或 Vite）有所不同。

Create React App 部署

步驟 1：設定 homepage

在 package.json 加入 homepage 欄位：

{
  "name": "my-react-app",
  "homepage": "https://username.github.io/repo-name",
  "scripts": {
    "build": "react-scripts build"
  }
}

如果是 User Site（username.github.io），homepage 設為：

{
  "homepage": "https://username.github.io"
}

步驟 2：安裝 gh-pages 套件

npm install --save-dev gh-pages

步驟 3：新增部署指令

在 package.json 的 scripts 加入：

{
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

步驟 4：執行部署

npm run deploy

這個指令會：
1. 先執行 npm run build 產生靜態檔案到 build/ 資料夾
2. 把 build/ 資料夾的內容推送到 gh-pages 分支
3. GitHub Pages 自動從 gh-pages 分支發布

步驟 5：設定 GitHub Pages

到 Repository 的 Settings → Pages，確認 Source 選擇 gh-pages 分支。

Vite + React 部署

如果你用 Vite 建立 React 專案，設定方式不太一樣。

步驟 1：設定 vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/repo-name/'  // 改成你的 Repository 名稱
})

如果是 User Site，base 設為 '/'：

export default defineConfig({
  plugins: [react()],
  base: '/'
})

步驟 2：Build 並部署

npm run build

Build 完成後，dist/ 資料夾就是要部署的內容。你可以：
- 手動把 dist/ 內容推送到 gh-pages 分支
- 使用 gh-pages 套件自動部署
- 使用 GitHub Actions 自動部署（推薦）

React Router 路由問題

如果你用 React Router，直接存取子路徑會 404。解決方式：

方法 1：改用 HashRouter

import { HashRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <HashRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </HashRouter>
  );
}

網址會變成 username.github.io/repo-name/#/about。

方法 2：建立 404.html fallback

在 public/ 資料夾建立 404.html，內容參考 GitHub Pages 404 錯誤完整解決指南。

React 部署卡關？VibeFix 30 分鐘搞定你的部署問題

React 的 base path、路由設定很容易搞混，一個設定錯誤就會導致整個網站壞掉。如果你試了很多方法還是不行，讓 VibeFix 的專家來幫你。

立即預約諮詢 →

Vue.js (Vue CLI / Vite) 部署教學

Vue 的部署方式和 React 類似，主要差別在設定檔的名稱和格式。

Vue CLI 部署

步驟 1：建立 vue.config.js

在專案根目錄建立 vue.config.js：

module.exports = {
  publicPath: process.env.NODE_ENV === 'production'
    ? '/repo-name/'  // 改成你的 Repository 名稱
    : '/'
}

這樣設定的好處是：開發時（npm run serve）用 /，build 時才加上 Repository 名稱。

如果是 User Site：

module.exports = {
  publicPath: '/'
}

步驟 2：Build

npm run build

Build 完成後，靜態檔案會在 dist/ 資料夾。

步驟 3：部署到 gh-pages

# 安裝 gh-pages
npm install --save-dev gh-pages

# 在 package.json 加入
# "deploy": "gh-pages -d dist"

# 執行部署
npm run deploy

Vite + Vue 部署

步驟 1：設定 vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/repo-name/'  // 改成你的 Repository 名稱
})

步驟 2：Build 並部署

npm run build
# dist/ 資料夾就是要部署的內容

Vue Router 設定

Vue Router 同樣需要設定 base：

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory('/repo-name/'),  // 加上 Repository 名稱
  routes: [
    // 你的路由設定
  ]
})

如果不想處理路由問題，也可以改用 hash mode：

import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    // 你的路由設定
  ]
})

Angular 部署教學

Angular 的設定比較多，但流程差不多。

步驟 1：Build 時指定 base-href

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

這個參數會在 index.html 的 <base> 標籤設定正確的路徑。

步驟 2：設定 angular.json（可選）

如果不想每次都打參數，可以在 angular.json 設定：

{
  "projects": {
    "your-project-name": {
      "architect": {
        "build": {
          "configurations": {
            "production": {
              "baseHref": "/repo-name/"
            }
          }
        }
      }
    }
  }
}

步驟 3：部署

Build 完成後，靜態檔案在 dist/project-name/ 資料夾。

# 安裝 angular-cli-ghpages
npm install -g angular-cli-ghpages

# 部署
npx angular-cli-ghpages --dir=dist/your-project-name

Angular Router 設定

Angular 預設使用 HTML5 pushState 路由，需要額外設定：

// app-routing.module.ts
@NgModule({
  imports: [RouterModule.forRoot(routes, {
    useHash: true  // 使用 hash 路由避免 404
  })],
  exports: [RouterModule]
})
export class AppRoutingModule { }

Hugo 靜態網站部署教學

Hugo 是很受歡迎的靜態網站生成器，部署到 GitHub Pages 相對簡單。

步驟 1：設定 config.toml

baseURL = "https://username.github.io/repo-name/"

如果是 User Site：

baseURL = "https://username.github.io/"

步驟 2：Build

hugo

Hugo 會把靜態檔案產生到 public/ 資料夾。

步驟 3：部署

你有幾種選擇：

選項 A：部署 public 資料夾到 gh-pages

# 安裝 gh-pages
npm install -g gh-pages

# 部署
gh-pages -d public

選項 B：使用 Git Submodule

把 public/ 設為指向 gh-pages 分支的 submodule，這是 Hugo 官方推薦的方式。

選項 C：使用 GitHub Actions（推薦）

後面會提供完整的 workflow 範例。

主題相容性注意事項

部分 Hugo 主題可能會有路徑問題，特別是處理 CSS、JavaScript、圖片的方式。確認主題使用的是相對路徑，或正確使用 Hugo 的 relURL 和 absURL 函數。

Next.js 靜態匯出部署教學

Next.js 預設是 Server-side Rendering，但可以匯出成靜態網站。

Next.js 靜態匯出的限制

使用 output: 'export' 時，以下功能無法使用：

• API Routes
• Server-side Rendering (getServerSideProps)
• Image Optimization（需要設定 unoptimized: true）
• Incremental Static Regeneration
• Middleware

如果你需要這些功能，建議使用 Vercel 部署。

框架部署比較表

不確定該用哪個框架？這邊幫你整理比較：

推薦使用情境：

• 個人部落格：Hugo（快速、簡單）
• 作品集網站：Vue 或 React
• 專案文件：Hugo 或 Next.js
• 複雜 Web App：React 或 Vue（但考慮用 Vercel 部署）

不確定該用哪個框架？

諮詢 VibeFix 專家建議 →

常見錯誤與解決方案

部署框架網站時，最常遇到這些問題。

空白頁面

症狀：網站顯示空白，沒有任何內容。

原因：
- Base path 沒設定或設定錯誤
- JavaScript 檔案載入失敗

解決方式：
1. 開 DevTools → Console 看錯誤訊息
2. 檢查 Network 頁籤，確認 JS 檔案有成功載入
3. 確認 base path 設定正確

資源載入失敗

症狀：頁面跑出來但沒有樣式，圖片也不顯示。

原因：
- CSS、圖片的路徑沒有包含 base path

解決方式：
1. 確認框架設定的 base/publicPath 正確
2. 檢查靜態資源是否放在正確位置（public 或 assets 資料夾）
3. 使用框架提供的路徑處理方式，不要硬寫路徑

路由問題

症狀：首頁正常，點連結到其他頁面正常，但重新整理就 404。

原因：
- 前端路由 vs 後端路由的差異

解決方式：
- 使用 Hash 路由模式
- 建立 404.html fallback

詳細解決方式請參考 GitHub Pages 404 錯誤完整解決指南。

框架部署問題很多？讓 VibeFix 幫你一次解決

不管是 base path 設定、路由問題，還是 build 錯誤，VibeFix 的專家都能幫你快速排除。我們處理過各種框架的部署問題，讓你的網站順利上線。

立即預約諮詢 →

搭配 GitHub Actions 自動部署

手動執行 npm run deploy 很麻煩，設定 GitHub Actions 後，只要推程式碼就會自動部署。

React/Vue/Angular 通用 Workflow

在 .github/workflows/deploy.yml 建立：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist  # React CRA 改成 ./build

Hugo Workflow

name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

想深入了解 GitHub Actions 設定？請參考 GitHub Actions 自動部署完整教學。

總結與延伸閱讀

框架部署到 GitHub Pages 雖然比純 HTML 複雜，但只要搞懂 base path 設定和 build 流程，其實不難。

重點回顧

1. 理解限制：GitHub Pages 只支援靜態網站，框架需要 build
2. 設定 base path：Project Site 必須設定正確的 base path
3. 處理路由：SPA 路由需要用 Hash 模式或 404 fallback
4. 自動部署：使用 GitHub Actions 可以省去手動部署的麻煩

延伸閱讀

• 部署後出現 404？→ GitHub Pages 404 錯誤完整解決指南
• 想設定自動部署？→ GitHub Actions 自動部署完整教學
• 想回顧基礎？→ 返回 GitHub Pages 完整教學

框架部署遇到問題？VibeFix 幫你搞定

VibeFix 專門處理各種部署問題，不管你用的是 React、Vue、Angular 還是其他框架，我們都能幫你順利上線。

立即預約諮詢 →

FAQ

React 專案如何部署到 GitHub Pages？

React 專案部署到 GitHub Pages 的關鍵步驟：1) 在 package.json 設定 homepage 為你的 GitHub Pages 網址；2) 安裝 gh-pages 套件；3) 新增 predeploy 和 deploy 腳本；4) 執行 npm run deploy。如果使用 Vite，則要在 vite.config.js 設定 base 為 Repository 名稱。

Vue 部署 GitHub Pages 要設定什麼？

Vue 部署的關鍵是設定 publicPath。在 vue.config.js 中設定 publicPath: '/repo-name/'（把 repo-name 換成你的 Repository 名稱）。如果使用 Vue Router，也要設定 router 的 base 參數。Vite + Vue 則是在 vite.config.js 設定 base。

Next.js 可以部署到 GitHub Pages 嗎？

可以，但有限制。Next.js 需要使用 output: 'export' 模式匯出成靜態檔案。這表示你不能使用 API Routes、Server-side Rendering、Image Optimization 等需要伺服器的功能。如果你需要這些功能，建議使用 Vercel 部署。

哪個框架最容易部署到 GitHub Pages？

Hugo 是最容易部署的，因為它本身就是靜態網站生成器，build 速度快，設定也簡單。如果你的目標是部落格或文件網站，Hugo 是很好的選擇。React 和 Vue 難度中等，主要是要處理 base path 和路由設定。Angular 相對最複雜，設定項目比較多。