跳到主要內容
← 回到學習

學習 · 部署與DevOps

React專案無法正常Github Action

By Kurau3 分鐘閱讀

目錄 · 5 個段落
  1. 01完整 workflow YAML
  2. 02各框架的 build folder 對照
  3. 03常見錯誤與解法
  4. 042026 替代方案
  5. 05CI/CD 多階段範例

React 專案 GitHub Actions 部署

TL;DR
基本 workflow:checkout → setup-node → npm ci → npm run build → 部署 GitHub Pages。最常踩 exit code 128,要去 Settings → Actions → General → Workflow permissions 改成 Read and write。

完整 workflow YAML

# .github/workflows/deploy.yml
name: Deploy via GitHub Actions
 
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
 
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
 
    strategy:
      matrix:
        node-version: [20.x]    # ⭐ 2026 用 LTS 20+ 或 22
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
 
      - run: npm ci
      - run: npm run build --if-present
        env:
          CI: false              # ⭐ 避免 warning 變 error
 
      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: build          # CRA 用 build,Next.js 用 out,Vite 用 dist
yaml

各框架的 build folder 對照

框架build 後 folder
CRAbuild
Vitedist
Next.js(static export)out(要 next.config.js 加 output: 'export')
Astrodist
SvelteKitbuild

常見錯誤與解法

1. exit code 128 — 部署失敗

The deploy step encountered an error: The process '/usr/bin/git' failed with exit code 128

原因:GitHub Action 沒有寫入權限。

解法:

  1. Settings → Actions → General
  2. 找到 Workflow permissions 區塊
  3. 選 Read and write permissions
  4. 儲存後 re-run failed job

2. treating warnings as errors because process.env.CI = true

CRA 把 warning 當 error 卡住 build。解法:

- run: npm run build
  env:
    CI: false                # ⭐ 加這行
yaml

或者根治:把 warning 都修掉(更好)。

3. Cache 沒命中,每次 install 慢

# ✅ 用 actions/setup-node@v4 內建 cache
uses: actions/setup-node@v4
with:
  node-version: 20.x
  cache: 'npm'              # ⭐ 自動 cache node_modules
 
# 或更精細控制
uses: actions/cache@v4
with:
  path: ~/.npm
  key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
yaml

4. Next.js base path 問題(部署到 user.github.io/repo)

// next.config.js
const isProd = process.env.NODE_ENV === 'production';
module.exports = {
  output: 'export',
  basePath: isProd ? '/my-repo' : '',
  assetPrefix: isProd ? '/my-repo/' : '',
  images: { unoptimized: true },   // ⭐ 靜態 export 不能用 next/image 優化
};
javascript

2026 替代方案

直接用 GitHub Pages 內建 Action(更新)

name: Deploy to GitHub Pages
 
on:
  push:
    branches: [main]
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: pages
  cancel-in-progress: true
 
jobs:
  build:
    runs-on: ubuntu-latest
    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/upload-pages-artifact@v3
        with:
          path: ./dist
 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
yaml

這是 GitHub 官方的新流程,不需要 JamesIves/github-pages-deploy-action。配 permissions 設定就不用改 Workflow permissions UI。

Vercel / Netlify(更簡單)

其實大部分時候根本不用寫 Action:

  • Vercel:GitHub repo connect 後自動部署,5 分鐘起站
  • Netlify:同上
  • Cloudflare Pages:更快、免費額度大
# Vercel CLI 一鍵部署
npm i -g vercel
vercel
bash

2026 年除非有特殊需求,別用 GitHub Pages。Vercel / Netlify / Cloudflare Pages 體驗壓倒性勝出。

CI/CD 多階段範例

name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: 'npm' }
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test
 
  build:
    needs: test           # ⭐ 測試通過才 build
    runs-on: ubuntu-latest
    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/upload-artifact@v4
        with:
          name: dist
          path: dist/
 
  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'    # ⭐ 只有 main branch 才 deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist, path: ./dist }
      # ... 部署步驟
yaml

這樣 PR 會跑 test + build,只有 merge 進 main 才 deploy,標準 flow。

目錄