GitHub Pages

GitHub Actions 自動部署 GitHub Pages 完整教學：CI/CD 工作流程設定指南

2025-12-15 28 分鐘閱讀 VibeFix

GitHub Actions 自動部署 GitHub Pages 完整教學：CI/CD 工作流程設定指南

每次更新網站都要手動執行 npm run build 然後 npm run deploy，是不是覺得很麻煩？GitHub Actions 可以幫你自動化這個流程。設定完成後，只要推程式碼到 GitHub，網站就會自動更新。

這篇文章會從最基本的 CI/CD 概念開始，帶你一步步建立自動部署的 workflow。不管你是用純 HTML、React、Vue 還是 Hugo，都能找到適合的設定範例。

為什麼需要 GitHub Actions 自動部署？

先來理解一下為什麼要花時間設定自動部署。

手動 vs 自動部署

手動部署流程：
1. 寫程式碼
2. 本地執行 build
3. 確認 build 成功
4. 執行部署指令
5. 等待部署完成
6. 確認網站更新

自動部署流程：
1. 寫程式碼
2. 推上 GitHub
3. 自動完成，網站更新

每次改一行程式碼都要手動部署，累積起來是很大的時間浪費。

manual-vs-auto-deploy-comparison

CI/CD 是什麼？

CI/CD 是兩個概念的組合：

CI（Continuous Integration）持續整合：
- 頻繁地把程式碼合併到主分支
- 每次合併都自動執行測試
- 確保程式碼品質

CD（Continuous Deployment）持續部署：
- 程式碼合併後自動部署
- 不需要手動操作
- 縮短從開發到上線的時間

對 GitHub Pages 來說，主要用到的是 CD：推程式碼 → 自動部署。

自動化帶來的效率提升

  • 節省時間：不用每次都執行手動步驟
  • 減少錯誤：不會忘記某個步驟或打錯指令
  • 更快迭代：改完就部署，縮短反饋循環
  • 版本追蹤：每次部署都有 Git commit 記錄

GitHub Actions 基礎概念

在寫 workflow 之前，先了解幾個重要概念。

Workflow（工作流程）

Workflow 是你定義的自動化流程，用 YAML 格式寫在 .github/workflows/ 資料夾裡面。一個 Repository 可以有多個 workflow。

Job（工作）

一個 Workflow 可以包含多個 Job。每個 Job 會在獨立的虛擬機器上執行。多個 Job 可以平行執行，也可以設定依賴關係。

Step（步驟）

Job 裡面的執行單位。每個 Step 可以是：
- 執行一個指令
- 使用一個 Action

Runner（執行器）

Runner 是執行 Job 的虛擬機器。GitHub 提供免費的 Runner（Ubuntu、Windows、macOS），你也可以用自己的伺服器。

Action（動作）

可重複使用的程式碼單元，由社群或官方提供。例如 actions/checkout 用來取得程式碼，peaceiris/actions-gh-pages 用來部署到 GitHub Pages。

github-actions-concept-hierarchy

建立第一個部署 Workflow

來實際動手建立一個 workflow。

步驟 1：建立 Workflow 檔案

在你的 Repository 建立以下檔案：

.github/
  workflows/
    deploy.yml

步驟 2：基本結構

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

這個 workflow 會在你推程式碼到 main 分支時觸發。

YAML 基本語法

YAML 是一種用縮排表示階層的格式：

# 這是註解
key: value                    # 鍵值對
list:                         # 列表
  - item1
  - item2
nested:                       # 巢狀結構
  key1: value1
  key2: value2

注意事項：
- 用空格縮排，不要用 Tab
- 冒號後面要有空格
- 字串有特殊字元時用引號包起來

觸發條件設定

on 區塊定義什麼時候觸發 workflow：

# 推送到 main 分支時觸發
on:
  push:
    branches: [ main ]

# 建立 PR 時觸發
on:
  pull_request:
    branches: [ main ]

# 手動觸發
on:
  workflow_dispatch:

# 定時觸發（每天凌晨 3 點）
on:
  schedule:
    - cron: '0 3 * * *'

# 多種條件組合
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

靜態網站自動部署範例

如果你的網站是純 HTML/CSS/JavaScript，不需要 build 步驟：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'  # 發布整個 Repository

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

這個 workflow 使用 GitHub 官方的 Pages 部署 Action，是目前推薦的方式。

設定 Repository 使用 GitHub Actions 部署

  1. 到 Repository Settings → Pages
  2. Source 選擇「GitHub Actions」
  3. 不需要選擇分支，因為 Actions 會處理

React/Vue 框架自動部署範例

框架專案需要先 build，再部署 build 結果。

React (Vite) 範例

name: Deploy React App

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

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

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Checkout
        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: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'  # Vite 的 build 輸出資料夾

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

重要：記得在 vite.config.js 設定正確的 base：

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

Vue 範例

Vue 的 workflow 跟 React 幾乎一樣，只需要確認 build 輸出資料夾：

# 其他部分相同，修改這一行
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'  # Vue CLI 和 Vite 都是 dist

記得在 vue.config.js 或 vite.config.js 設定 publicPath/base。

各框架的 build 設定詳細說明，請參考各框架的 build 設定詳細說明。

框架部署自動化很複雜？VibeFix 幫你設定完整 CI/CD 流程

設定 GitHub Actions 需要了解 YAML 語法、環境變數、權限設定等，搞錯一個地方就會部署失敗。如果你覺得太複雜，讓 VibeFix 的專家幫你設定。

立即預約諮詢 →

Hugo/Jekyll 自動部署範例

Hugo 範例

name: Deploy Hugo site

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

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

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive  # Hugo 主題常用 submodule

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true  # 如果用 SCSS 需要 extended 版本

      - name: Build
        run: hugo --minify

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './public'  # Hugo 輸出資料夾

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Jekyll 範例

Jekyll 是 GitHub Pages 原生支援的，但如果你想要更多控制（例如使用插件），可以用 GitHub Actions：

name: Deploy Jekyll site

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

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

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true

      - name: Build
        run: bundle exec jekyll build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './_site'  # Jekyll 輸出資料夾

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
github-actions-success-status

進階：環境變數與 Secrets 設定

有些設定不適合放在程式碼裡，需要用環境變數或 Secrets。

環境變數

在 workflow 中定義環境變數：

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MY_VAR: 'some value'
    steps:
      - name: Use env var
        run: echo $MY_VAR

Secrets

敏感資料（API Key、Token 等）要用 Repository Secrets：

  1. 到 Repository Settings → Secrets and variables → Actions
  2. 點擊「New repository secret」
  3. 輸入名稱和值

在 workflow 中使用：

steps:
  - name: Use secret
    env:
      API_KEY: ${{ secrets.MY_API_KEY }}
    run: echo "Using API key"

GITHUB_TOKEN

GITHUB_TOKEN 是 GitHub 自動提供的 Token，用來執行需要權限的操作（如部署）。不需要自己建立，直接使用即可：

permissions:
  contents: read
  pages: write
  id-token: write

# 使用方式
${{ secrets.GITHUB_TOKEN }}

自訂 Secrets 範例

假設你的網站需要 API Key：

steps:
  - name: Build with API key
    env:
      VITE_API_KEY: ${{ secrets.API_KEY }}
    run: npm run build

在 Vite 專案中使用：

// 在程式碼中使用
const apiKey = import.meta.env.VITE_API_KEY

部署失敗排錯指南

workflow 執行失敗時，怎麼找出問題？

常見錯誤

1. 權限不足

錯誤訊息：Error: Action failed with "not found"

解決方式：確認 permissions 區塊設定正確：

permissions:
  contents: read
  pages: write
  id-token: write

2. Build 失敗

錯誤訊息：npm run build failed

解決方式：
- 本地執行 npm run build 確認可以成功
- 檢查 Node.js 版本是否一致
- 確認所有依賴都在 package.json 裡

3. 套件安裝失敗

錯誤訊息：npm ci failed

解決方式：
- 確認 package-lock.json 有提交
- 刪除 node_modules 和 package-lock.json，重新 npm install 後提交

4. 路徑錯誤

錯誤訊息：path does not exist

解決方式：確認 upload-pages-artifact 的 path 設定正確

Actions Log 分析

  1. 到 Repository → Actions
  2. 點擊失敗的 workflow run
  3. 展開失敗的 step 查看詳細 log
  4. 錯誤訊息通常會標紅色

權限問題處理

如果看到權限相關錯誤：

  1. 確認 Repository Settings → Pages → Source 選擇「GitHub Actions」
  2. 確認 workflow 有正確的 permissions 設定
  3. 如果是 fork 的 Repository，可能需要在 Actions 頁面啟用 workflow

Actions 部署一直失敗？讓專家幫你檢查 workflow

GitHub Actions 的錯誤訊息有時候很難懂，找問題很花時間。VibeFix 的專家可以幫你快速診斷並修復 workflow 問題。

預約診斷服務 →

最佳實踐與效能優化

讓你的 workflow 跑更快、更穩定。

快取設定

每次 workflow 執行都要重新安裝套件很慢，用快取可以加速：

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # 自動快取 node_modules

或手動設定快取：

- name: Cache node modules
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

條件執行

只在特定條件下執行某些步驟：

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main'
    run: npm run deploy

  - name: Deploy to staging
    if: github.ref == 'refs/heads/develop'
    run: npm run deploy:staging

只在特定檔案變更時觸發

on:
  push:
    branches: [ main ]
    paths:
      - 'src/**'
      - 'public/**'
      - 'package.json'

這樣只修改 README 就不會觸發部署。

並行執行

多個 Job 可以平行執行：

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  lint:
    runs-on: ubuntu-latest
    steps:
      - run: npm run lint

  deploy:
    needs: [test, lint]  # 等 test 和 lint 都完成
    runs-on: ubuntu-latest
    steps:
      - run: npm run deploy
workflow-optimization-time-comparison

總結與延伸閱讀

GitHub Actions 讓你的部署流程自動化，推程式碼就能更新網站。

重點回顧

  1. 理解概念：Workflow、Job、Step、Action 的關係
  2. 建立 workflow：在 .github/workflows/ 建立 YAML 檔案
  3. 設定權限：確保有正確的 permissions
  4. 優化效能：使用快取、條件執行、並行處理

常用 Workflow 模板

最後整理一個通用模板，複製貼上再修改即可：

name: Deploy

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'  # 改成你的 build 輸出資料夾
      - uses: actions/deploy-pages@v4
        id: deployment

延伸閱讀

準備讓你的部署自動化了嗎？VibeFix 提供完整 CI/CD 設定服務

不管是簡單的靜態網站還是複雜的框架專案，VibeFix 都能幫你設定完善的自動部署流程。讓你專注在寫程式，部署的事交給自動化。

立即預約諮詢 →

FAQ

GitHub Actions 部署 GitHub Pages 免費嗎？

免費帳號每月有 2,000 分鐘的 GitHub Actions 執行時間，對大多數個人專案來說很夠用。一次典型的部署大約需要 1-3 分鐘，所以你每月可以部署幾百次。超過免費額度的話，可以升級 GitHub Pro（每月 3,000 分鐘）或購買額外分鐘數。

GitHub Actions 部署失敗怎麼辦？

先到 Repository 的 Actions 頁面查看失敗的 workflow run，展開失敗的 step 看詳細錯誤訊息。常見原因包括：權限設定不正確、build 指令失敗、套件安裝問題、路徑設定錯誤。建議先在本地確認 build 可以成功，再檢查 workflow 設定是否正確。

如何讓 push 後自動部署到 GitHub Pages？

在 Repository 建立 .github/workflows/deploy.yml 檔案，設定 on: push: branches: [main] 觸發條件，然後在 steps 中設定 build 和部署步驟。另外要到 Repository Settings → Pages 把 Source 改成「GitHub Actions」。這樣每次 push 到 main 分支就會自動觸發部署。

GitHub Actions 和手動部署哪個比較好？

自動部署幾乎在所有情況下都比手動部署好。優點包括：節省時間、減少人為錯誤、更快的迭代速度、完整的部署記錄。唯一需要手動部署的情況是：你想要更精細的控制，例如選擇性地部署某些變更。但即使如此，你也可以設定手動觸發的 workflow（workflow_dispatch）來達成。

github actions github pages 自動部署 github actions deploy github pages workflow CI/CD
分享文章：
V

VibeFix

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

這篇文章有幫到你嗎？

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

聯繫我們