使用Github Actions打包前端项目并自动上传到Github Pages分支

前言

之前写了一篇 Github Actions 怎么将build的内容发布到 Releases 上，这次想将前端的SPA项目搞一个在线预览的站点，但是又没有经济实力提供一个服务器来进行部署，所以就参考了下一些开源项目，发现他们都是用 Github Pages 来做在线预览的，所以我也想弄一个。

本篇文章就不细说基本内容了，想入门的可以看之前那篇：《使用Github Actions打包前端项目并自动上传到Releases》

教程

我本来的意思是，先用 Actions 打包后，再克隆一个仓库，切换到 Github Pages 的分支，将dsit目录里的内容复制到这个 Github Pages 的分支，再进行上传。

但是测试了好几次发现都会出现问题，应该是克隆的时候有限制，为此放弃了这种做法，好在也放弃了这个，我找到了一个官方的支持，官方是有维护一个仓库专门处理将打包内容上传到 Github Pages 的。

仓库地址：actions-gh-pages

使用这个动作库，可以很方便的将内容部署到 Github Pages 上。

创建一个 Github Pages 专用的git分支

我们需要创建一个专门的git分支，这个分支中只存打包后的文件，默认情况下很多人会创建分支名为：gh-pages 的分支，因为这个也是 actions-gh-pages 默认使用的分支名，当然我们也可以自定义的，比如我就是创建的：preview 分支名。

告诉大家一个小技巧，创建分支肯定会基于已有的分支创建，这就导致新分支会有很多用不上的文件，比如基于main分支创建的，肯定会有开发的代码，但是这些文件我们都不需要，我们可以使用 git reset --hard hash 来回退到最初的提交记录，一般情况下，初始的记录可能就只有一个 README.md文件，我们只需要强行推送回退后的内容到远程分支就行了。

这样git的记录就会少非常多的内容，使用也简洁。如果你不会操作，可以看这篇文章：《git 回退分支并覆盖远程分支》

分支创建好了，将分支里的文件全部删除，保留一个空分支即可。

创建 Github Pages

我们先去仓库的 Settings 页面，点击左侧的 Pages 菜单，将 Branch 的分支选择刚刚创建的 preview 分支，后面的目录根据自己项目情况选择是：/（root）根目录 还是文档类型的 /docs。我的是项目预览，所以使用根目录即可。

然后点击 save 保存。

此时pages就创建好了。

访问地址一般是：https://你的账号.github.io/仓库名/，比如我的就是：

https://mulingyuer.github.io/element-admin-template/

创建工作流文件

我们在主分支根目录中创建目录跟文件：.github/workflows/preview.yml

这个preview.yml文件名自己随意起。

创建完后写入以下内容：

name: 打包并输出到preview分支进行预览

# 检测只有主分支的push操作会触发该工作流
on:
  push:
    branches:
      - main
  workflow_dispatch: # 允许手动触发该工作流

jobs:
  build:
    name: 打包
    runs-on: ubuntu-latest
    permissions:
      contents: write # 确保有写权限

    steps:
      - name: 克隆仓库
        uses: actions/checkout@v4
        with:
          ref: main # 指定主分支

      - name: 指定Node.js版本
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: 安装pnpm
        run: npm install pnpm -g

      - name: 安装依赖
        run: pnpm install

      - name: 打包
        run: pnpm build --mode github-preview

      - name: 部署到preview分支
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          publish_branch: preview
          full_commit_message: ${{ github.event.head_commit.message }}

yml文件注意缩进问题，非常严格，如果使用vscode可以安装插件：GitHub Actions 辅助自己。

这个工作流需要注意两点：

第一就是contents: write，因为我们需要push内容到分支，所以需要保证有写入权限，这块写法是固定的，照抄就行了，没啥特殊改变。

第二就是使用 peaceiris/actions-gh-pages，可以看到后面跟了个 @v4 ，就是使用最新版v4，版本都可以从官方的仓库的分支上看到，官方的说明文档也有示例。

• github_token：使用 actions-gh-pages 需要配置 github_token 这个值，不然就会push失败，而对应的值我们直接用默认的环境变量就行了，这个值之前的文章有解释，就不多说明了。
• publish_dir：表示需要push的目录是哪个，我们前端spa的项目，当然是dist目录。
• publish_branch：表示需要push到哪个分支，填刚刚创建的分支名。
• full_commit_message：表示push的时候使用全量的commit message，一般也不是很重要，不要也可以。

完事后我们提交到主分支就行了。

此时github就会触发该动作进行打包构建。

在项目介绍中使用 Github Pages

我们可以在仓库的 About 中设置访问链接。

直接勾选：Use your GitHub Pages website 就行了，他会自动给你设置好链接地址，接着 save changes 即可享受。