React專案無法正常Github Action
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
各框架的 build folder 對照
| 框架 | build 後 folder |
|---|---|
| CRA | build |
| Vite | dist |
| Next.js(static export) | out(要 next.config.js 加 output: 'export') |
| Astro | dist |
| SvelteKit | build |
常見錯誤與解法
1. exit code 128 — 部署失敗
The deploy step encountered an error: The process '/usr/bin/git' failed with exit code 128
原因:GitHub Action 沒有寫入權限。
解法:
- Settings → Actions → General
- 找到 Workflow permissions 區塊
-
選
Read and write permissions - 儲存後 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 # ⭐ 加這行
或者根治:把 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') }}
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 優化
};
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
這是 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
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 }
# ... 部署步驟
這樣 PR 會跑 test + build,只有 merge 進 main 才 deploy,標準 flow。