GitHub Pages、Actions 與進階應用

適合程式碼與文件分開管理——只部署 docs/ 資料夾的內容。

my-project/
├── src/           ← 程式碼（不會被部署）
├── docs/          ← 網站內容（會被部署）
│   ├── index.html
│   ├── style.css
│   └── guide.html
├── README.md
└── package.json

1. 將網站檔案放在 docs/ 資料夾中。
2. Settings → Pages → Branch: main, 路徑: /docs。

最靈活的方式——用 GitHub Actions 自訂建置流程。適合需要編譯的框架（如 React、Vue、Jekyll）。

1. Settings → Pages → Source 選擇 GitHub Actions。
2. GitHub 會建議適合你專案的 workflow 範本。
3. 或自行建立 .github/workflows/deploy.yml。

（詳見本章後半的 Actions 段落。）

# 在 GitHub 建立一個新的 Public Repo（名稱如 my-site）

# 連結遠端並推送
$ git remote add origin git@github.com:你的帳號/my-site.git
$ git push -u origin main

1. 在 GitHub Repo 頁面 → Settings → Pages。
2. Source: Deploy from a branch。
3. Branch: main，路徑: / (root)。
4. 點擊 Save。
5. 等候 1-2 分鐘，頁面上方會出現網站的 URL。
6. 點擊連結，你的網站就上線了！🎉

# 只在 src/ 目錄的程式碼變更時才跑測試
on:
  push:
    paths:
      - 'src/**'
      - 'tests/**'
    paths-ignore:
      - '**.md'        # 修改文件不觸發
      - '.github/**'   # 修改 workflow 不觸發

使用 paths 只在特定目錄有變更時觸發，搭配 paths-ignore 排除不相關的變更。

# 每週一早上 9 點（UTC）自動執行
on:
  schedule:
    - cron: '0 9 * * 1'

# cron 語法：分 時 日 月 星期
# ┌──── 分鐘 (0-59)
# │ ┌──── 小時 (0-23)
# │ │ ┌──── 日 (1-31)
# │ │ │ ┌──── 月 (1-12)
# │ │ │ │ ┌──── 星期 (0-6，0=週日)
# │ │ │ │ │
# * * * * *

# 更多範例：
# '0 0 * * *'    → 每天午夜
# '30 8 * * 1-5' → 週一到週五 08:30
# '0 */6 * * *'  → 每 6 小時

# 在 GitHub 網頁上手動觸發，可帶自訂參數
on:
  workflow_dispatch:
    inputs:
      environment:
        description: '部署目標環境'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      debug:
        description: '啟用除錯模式'
        required: false
        type: boolean
        default: false

workflow_dispatch 讓你可以在 Actions 頁面上按下 Run workflow 按鈕手動觸發，還能傳入自訂參數。

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [18, 20, 22]
        # 這會自動產生 3×3 = 9 個 Job 組合！
    steps:
      - uses: actions/checkout@v4
      - name: 設定 Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

矩陣策略會自動展開所有組合，上面的範例會同時跑 9 個 Job（3 個 OS × 3 個 Node 版本），確保你的程式碼在各種環境都能正常運作。

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  # 只在 main 分支、且 test 通過後才部署
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - run: echo "只有 push 到 main 才會跑到這裡"

  # 即使前面的 Job 失敗也要執行的清理工作
  cleanup:
    needs: [test, deploy]
    runs-on: ubuntu-latest
    if: always()              # ← 不管前面是否失敗都執行
    steps:
      - run: echo "清理暫存資源..."

if 條件可以使用 github context（如分支名、事件類型）來決定是否執行。always() 表示無論前面 Job 是否失敗都會執行。

# .github/workflows/test.yml
name: Run Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 程式碼
        uses: actions/checkout@v4

      - name: 安裝 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 安裝依賴
        run: npm ci

      - name: 執行測試
        run: npm test

push 或建立 PR 時自動執行 Node.js 測試。uses 引用的是 GitHub Marketplace 上的現成 Action。

# .github/workflows/deploy-pages.yml
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: '.'

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

這是使用 Actions 部署 GitHub Pages 的官方推薦方式。