基于Github Actions实现前端CI/CD持续集成与部署

一、概述

随着前端技术的迅猛发展，Web应用程序的构建和部署变得越来越复杂，因此诞生了各种CI/CD工具，如：Jenkins、Github Actions、gitlab ci、gitlab runner。GitHub Actions作为一种强大的自动化工具，为前端开发提供了持续集成（CI）和持续部署（CD）的解决方案，极大地提高了开发效率和软件质量。通过在代码库中定义自定义工作流程，GitHub Actions能够整合JavaScript框架（如React、Vue）、模块打包工具（如Webpack、Vite）和测试框架（如Jest）等多种技术栈和工具链，自动执行代码检查、单元测试和集成测试，确保代码质量。此外，GitHub Actions与GitHub平台的深度集成，使得团队可以在统一的平台上高效协作和管理，快速响应需求变化，适应市场和用户需求。基于GitHub Actions实现的前端CI/CD，不仅提升了前端开发的自动化水平，还优化了团队的工作流程，增强了发布的频率和可靠性，为前端开发带来了革命性的改变。

二、实践

GitHub Pages

GitHub Pages 是 GitHub 提供的一项服务，它允许用户通过 GitHub 存储库免费托管静态网站。用户可以使用 HTML、CSS 和 JavaScript 来构建他们的网站，并将其发布在 GitHub 的子域名上。只需创建一个名为 username.github.io 的存储库，提交你的网站文件，GitHub 就会自动生成并托管该网站。

创建项目和仓库

使用前端脚手架（如：vite、vue-cli、create-react-app）创建一个前端项目，并打开Github创建一个新的仓库，初始化项目git，将代码提交到github远程仓库。

获取github的token

打开你的github，点开头像 > Settings > Developer settings > tokens(classic) > Generate new token > Generate new token classic > 按照提示完成token的获取

Personal Access Tokens (Classic) (github.com)

设置仓库构建分支

进入github项目仓库设置，Settings > Pages > Branch (选择需要构建的分支gh-pages) > Save > Actions

注意：红框链接是我们部署后要访问的链接

一些git分支操作：

• 创建新分支：git checkout -b <branch-name>

• 发布新分支：git push origin <branch-name>

• 删除本地分支：git branch -d <branch-name>

• 强制删除本地分支：git branch -D <branch-name>

• 删除远程分支：git push origin --delete <branch-name>

创建并配置工作流文件

Actions > New workflow > set up a workflow yourself，或者在我们项目目录下新建.github/workflows/main.yml文件并配置。

./.github/workflows/main.yml配置文件

name: deploy

#监听push操作
on:
  push:
    branches:
      - cicd # 这里只配置了cicd分支，所以只有推送cicd分支才会触发以下任务
    paths-ignore: # 下列文件的变更不会触发部署
      - README.md

jobs:
  build-and-deploy: # 任务ID
    runs-on: ubuntu-latest # 运行环境
    steps: # 步骤
      # 官方action，将代码拉取到虚拟机
      - name: Checkout
        uses: actions/checkout@v2
        with:
          persist-credentials: false # 这个设置很重要，尤其是在部署到 public repository 时

      # 启用node
      - name: Setup Node.js
        uses: actions/setup-node@master
        with:
          node-version: '20.x'
          # cache: 'pnpm'

      # 安装pnpm
      - name: Install pnpm
        run: |
          npm install -g pnpm
          echo "Verify pnpm version"
          pnpm -v

      # 添加pnpm到环境变量
      - name: Add pnpm to PATH
        run: echo "$(npm prefix -g)/bin" >> $GITHUB_PATH

      # 设置pnpm缓存
      - name: Cache pnpm modules
        uses: actions/cache@v2
        with:
          path: |
            ~/.pnpm-store
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      # 安装项目依赖
      - name: Install dependencies
        run: pnpm install

      # 打包构建
      - name: Build
        run: pnpm run build

      # 部署到 Github Pages
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          branch: gh-pages # 部署后提交到那个分支
          github_token: ${{ secrets.ADMIN_PRO_CICD }} # 
          # deploy_key: ${{ secrets.ADMIN_PRO_CICD }} # 使用密钥部署 Setting -> Secrets -> New repository secret -> Name: DEPLOY_KEY -> Value: your deploy key
          publish_dir: ./dist # 这里填打包好的目录名称
          folder: dist # 这里填打包好的目录名称
          # publish_branch: gh-pages
          commit_message: '自动化部署'

测试自动化部署

开发完项目新功能后提交代码到github仓库，测试github actions自动化部署。

构建部署打包报错：没有安装vue依赖，因为项目package.json没有安装vue记录。

安装vue之后有报错

取消branch: gh-pages、github_token 注释，并添加folder: dist

重新测试部署，又报错了，git提交代码触发CD/CD的分支和部署到的gh-pages不能是一个分支。

on.push.branches不能是gh-pages，我这里改为cdcd分支

github显示部署成功，但访问部署之后的链接出现空白，js资源请求报错404

打包编译文件路径配置有问题，js资源文件，加载的路径地址不对，需要修改项目打包配置我文件

// ./vite.config.js
export default defineConfig({
  plugins: [vue(), vueJsx()],
  base:'./',// 将根路径换成相对路径
  // ...
})

// 基于webpack构建的
// webpack.config.js or vue.config.js
module.exports = {
  publicPath: './',
  // ...
}

重新测试部署后，成功访问页面。到此基本实现了github actions 自动化部署，还可以配置自定义的域名。

设置自定义域名

Pages (github.com)

自行购买注册域名。返回到项目的GitHub pages页面，将购买的域名添加在Custom domain中，点击save，可以看到pages的地址变成了我们自己的域名，访问它就会看到你的网站了

后期Action报错与解决

Error: Missing download info for actions/cache@v2

发生时间：2025年4月4日13:01:37

解决时间：2025年4月4日13:09:16

错误描述：

Current runner version: '2.323.0'

...

Download immutable action package 'actions/checkout@v2'

Download action repository 'actions/setup-node@master'

Error: Missing download info for actions/cache@v2

详细描述：

​

解决办法： 修改.github/workflows/main.yml文件配置

 fatal: Authentication failed for 'https...'

发生时间：2025年4月4日13:18:37

解决时间：2025年4月5日12:07:43

错误描述：密钥过期，身份验证失败

详细描述：

/usr/bin/git push origin gh-pages

remote: Invalid username or password.

fatal: Authentication failed for 'https'

Error: Action failed with "The process '/usr/bin/git' failed with exit code 128"

解决办法： 更新密钥，个人账号 >> Setting >> Deploy Setting >> Tokens (classic) >> 更新对应Token >> 项目Setting >> Secrets and variables >> Actions  >> 更新对应Token或新增（Name要与写在main.yml里一致，把Tokens (classic)复制的token粘贴给Secret）

 

三、参考文献

远程仓库.github/workflow的 yml如何配置_github yml文件-优快云博客