使用 GitHub Actions 构建、部署 Next.js 并将其托管到 GitHub Pages

本文是一个简单教程, 将 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..: 指定触发事件时，可以限定分支或标签
• jobs..name: workflow 文件的主体是jobs字段, 表示要执行的一项或多项任务
• jobs..needs: needs 字段指定当前任务的依赖关系, 即运行顺序
• jobs..runs-on: runs-on 字段指定运行所需要的虚拟机环境, 它是必填字段
• jobs..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/

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

所以 需要通过配置使 Next.js 得到 /

有两个相关的配置选项: basePath 和 assetPrefix

将 basePath 设置为 / 将生成 GitHub Pages 可访问链接

将 assetPrefix 设置为 // 将生成 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 为 /

next.config.js

const isGithubActions = process.env.GITHUB_ACTIONS || false

let assetPrefix = ''
let basePath = '/'

if (isGithubActions) {
  // 去掉 `/`
  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 实现开源项目的自动化