本文是一個簡單教程, 將 Next.js 製作的靜態網站, 通過 GitHub Actions構建打包，最後將其自動化部署到 GitHub Pages用於展示

介紹:

• GitHub Actions 是 GitHub 的持續集成服務
• Github Pages 是 GitHub的靜態站點託管服務
• Next.js 是 基於 React構建 服務端渲染 (SSR)應用的框架

在本教程中的步驟:

1. 將本地開發好的 Next.js項目上傳到 GitHub, 啓用 GitHub Pages服務
2. 配置 GitHub Actions workflow, 以便在 push時自動構建、導出和部署 靜態網站到 GitHub Pages
3. 修改 Next.js的配置選項以適應 GitHub Actions URL結構

1. 配置 GitHub Pages

GitHub Pages 必須在每個 repo 的基礎上打開, 打開它時，您可以選擇要服務的分支

通常是將服務設置在 .gh-pages分支

1. 在瀏覽器中, 打開 GitHub 裏的項目 repo
2. 在 Settings > Pages > Source中, 將 Branch分支設定在 .gh-pages 並點擊 Save保存配置

2. 配置 GitHub Actions

GitHub Actions 是一種工具，可讓你在 GitHub 倉庫中執行不同的自動化操作

它允許你創建 自定義工作流，你可以使用這些工作流來自動化開發過程，例如 構建、 測試 和 部署代碼

2.1 如何在倉庫中設置 GitHub Actions

GitHub Actions 的配置文件叫做 workflow 文件，存放在代碼倉庫的 .github/workflows目錄

workflow 文件採用 YAML 格式, 文件名可以任意取, 但是後綴名統一為.yml, 比如 actions.yml

一個庫可以有多個 workflow 文件, GitHub 只要發現 .github/workflows 目錄裏面有 *.yml文件, 就會自動運行該文件

2.2 GitHub Actions 字段

• name: name 字段是 workflow 的名稱。如果省略該字段，默認為當前 workflow 的文件名
• on: on 字段指定觸發 workflow 的條件，通常是某些事件
• on.<push|pull_request>.<tags|branches>: 指定觸發事件時，可以限定分支或標籤
• jobs.<job_id>.name: workflow 文件的主體是jobs字段, 表示要執行的一項或多項任務
• jobs.<job_id>.needs: needs 字段指定當前任務的依賴關係, 即運行順序
• jobs.<job_id>.runs-on: runs-on 字段指定運行所需要的虛擬機環境, 它是必填字段
• jobs.<job_id>.steps: steps 字段指定每個 Job 的運行步驟，可以包含一個或多個步驟, 每個步驟都可以指定以下三個字段

2.3 使用到的腳本

• Setup Node.js environment: 配置 Node.js環境
• Setup pnpm: 配置 Pnpm安裝依賴

• Deploy to GitHub Pages: 提供 部署能力

  • Optional 參數説明

2.4 完整的配置

.github/workflows/actions.yml

name: Actions CI - Next.js version 12 static site export, GitHub Actions Build and Deploy
on:
  push:
    branches: [ main ]
# 執行的一項或多項任務
jobs:
  build-and-deploy:
    # 運行在虛擬機環境ubuntu-latest
    # https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on
    runs-on: ubuntu-latest
    steps:
    - name: 獲取源碼  🛎️
      uses: actions/checkout@v3
    - name: Node環境版本 🗜️
      uses: actions/setup-node@v3
      with:
        node-version: 18
    - name: 安裝 Pnpm 🧬
      uses: pnpm/action-setup@v2
      id: pnpm-install
      with:
          version: 7
          run_install: true
    - name: 安裝依賴 ⚙️
      run: pnpm install
    - name: 打包 🏗️
      run: |
        npm run build
        touch out/.nojekyll
    - name: 部署 🚀
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        branch: gh-pages
        folder: out
        clean: true

2.5 VS Code 開發體驗優化

通過安裝 VS Code官方插件 Github Actions來更直觀的 管理工作流、查看工作流 運行歷史記錄並幫助 創作工作流

插件配置 注意事項:

1. 設置 VS Code編輯器登錄 GitHub賬號, 並且綁定
2. 將 remote名稱 設置為上傳 GitHub的 remote名稱, 默認值: origin

3. 勾選上圖 Auto-refresh 自動刷新, 可以實時查看 workflow工作流狀態

3. 配置 Next.js

3.1 配置路徑

Next.js的 next/image、next/link 和 next/router 指定路徑是相對於 /的

而 GitHub Pages 託管站點的URL為: https://<你的github name>.github.io/<repo>

如: https://didilinkin.github.io/next-static-site-antd/

所以 需要通過配置使 Next.js 得到 /<repo>

有兩個相關的配置選項: basePath 和 assetPrefix

將 basePath 設置為 /<repo name> 將生成 GitHub Pages 可訪問鏈接

將 assetPrefix 設置為 /<repo name>/ 將生成 GitHub Pages 可訪問圖像

next.config.js

const repo = 'change-me-to-your-repo'
const assetPrefix = `/${repo}/`
const basePath = `/${repo}`

module.exports = {
  assetPrefix: assetPrefix,
  basePath: basePath,
}

讓我們將這部分配置應用於 GitHub Pages

我們會通過使用 GitHub Actions 導出靜態網站 拷貝到 GitHub Pages (詳情如下)

利用 GitHub 自動為我們添加的 環境變量

當 GitHub Actions 正在運行進程時, GITHUB_ACTIONS 為 true

GITHUB_REPOSITORY 為 <owner>/<repo>

next.config.js

const isGithubActions = process.env.GITHUB_ACTIONS || false

let assetPrefix = ''
let basePath = '/'

if (isGithubActions) {
  // 去掉 `<owner>/`
  const repo = process.env.GITHUB_REPOSITORY.replace(/.*?\//, '')

  assetPrefix = `/${repo}/`
  basePath = `/${repo}`
}

module.exports = {
  assetPrefix,
  basePath,
}

3.2 以下為完整的配置

next.config.js

/** @type {import('next').NextConfig} */
// 用於為靜態資源（如圖像、樣式表、JavaScript 文件等）設置 URL 前綴
// 這在將應用部署到自定義域名或 CDN 上時特別有用，因為它允許您將靜態資源存儲在不同的位置
let assetPrefix = `/${repo}/`

// 用於為應用設置基礎路徑
// 這在將應用部署到子目錄下時特別有用，因為它允許您指定應用所在的目錄
let basePath = `/${repo}`

const isGithubActions = process.env.GITHUB_ACTIONS || false

if (isGithubActions) {
  const repo = process.env.GITHUB_REPOSITORY.replace(/.*?\//, '')
  assetPrefix = `/${repo}/`
  basePath = `/${repo}`
}

const nextConfig = {
  assetPrefix,
  basePath,
  reactStrictMode: true,
  images: {
    unoptimized: true,
  },
}

module.exports = nextConfig

示例代碼

• GitHub Repository
• GitHub Pages 預覽頁面

常見問題

• Error: The deploy step encountered an error: The process '/usr/bin/git' failed with exit code "128" ❌ Notice: Deployment failed! ❌

  • 解決方案: 修改 workflow permissions
  • 解決方案: 修改 workflow permissions權限

參考鏈接

• (主要借鑑) 阮一峯 - GitHub Actions 入門教程
• (主要借鑑) Using GitHub Pages to Build, Deploy, and Host Next.js
• Using Composite GitHub Actions to make your Workflows smaller and more reusable
• GitHub Actions - Announcing the GitHub Actions extension for VS Code
• Deploying to Github Pages? Don't Forget to Fix Your Links
• Automating build/deploy CI/CD with GitHub Actions
• 如何使用 GitHub Actions 實現開源項目的自動化