【GitHub】基于Actions和Pages实现项目的自动构建与部署

00 缘由

手上有个前端项目使用的 Vite 来打包，我打算使用免费的 Github Actions 执行 workflows 工作流，实现自动打包，并通过 Github Pages 自动部署打包后的页面。

以前只知道用 Github Pages 部署静态内容，但对 Github Actions ^[1] 知之甚少，今天正式认识一下 GitHub workflows，探究之前在别人的项目根目录下总是见到的 .github/workflows/deploy.yml 文件的身份之谜。

话不多说，开始。

在 GitHub Actions 组织页面，我们可以看到它的自身定位是：

“Automate your GitHub workflows”

“自动化你的工作流”

GitHub Actions 提供了一种在 GitHub 仓库中直接自动化、定制和执行软件工作流程的方法，从而简化了开发、测试和部署过程^[2]。

02 如何使用 GitHub Actions ？

2.1 设置仓库的生成和部署源

若要为项目仓库配置为使用 GitHub Actions 进行构建和发布，需要执行以下操作^[3]：

打开 GitHub 的项目仓库。
在存储库名称下，单击 “Settings”（设置）。
在边栏的“Code and automation”（代码和自动化）部分中，单击“ Pages”。
在“Build and deployment”（生成和部署）的“Source”（源）下，选择“GitHub Actions”。
GitHub 将推荐多个入门工作流（workflows）。如果已有用于发布站点的工作流，可跳过此步骤。否则，需选择其中一个选项来创建 GitHub Actions 工作流。

2.2 寻找合适的 workflows 模板

注意：Vite 官方文档中也提供了提供了一个安装依赖项和使用 npm 构建的工作流程样本，请见部署静态站点：GitHub Pages

如果使用推荐的工作流，可以点击上图中“GitHub Actions”按钮下的 browse all workflows 或 create your own 链接。

如果点击后者 create your own ，GitHub会引导你在该仓库根目录下创建 .github/workflows/ 路径，并添加一个以 .yml 为后缀的文件，并且会为你填写了该文件的基本内容，只需基于此完善修改即可。



name: CI


on:
  
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  
  workflow_dispatch:


jobs:
  
  build:
    
    runs-on: ubuntu-latest

    
    steps:
      
      - uses: actions/checkout@v4

      
      - name: Run a one-line script
        run: echo Hello, world!

      
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

没错，GitHub Actions 的工作流就是根据上方这样的文件来执行的。通过按规则编辑它，就能按自己的想法自定义一些你想让它执行的步骤。

如果点击前者 browse all workflows ，你就可以在下方页面选择要开始的工作流，这些是 GitHub 为应对不同场景下提供的工作流分类模板：

上方预设的工作流模板大致分为以下几类：

Deployment（部署）：如将 Node.js 部署到 Azure Web 应用、部署到 Amazon ECS、部署至阿里云ACK、腾讯 Kubernetes 引擎等。
Security（安全）：如CodeQL 分析、强化扫描、SonarCloud、SonarQube等。
Continuous integration（持续集成）：简称为CI，如构建并测试 Node.js 项目、发布 Node.js 包等。
Automation（自动化）：如欢迎首次为存储库做出贡献的用户、根据更改的文件标记 pull requests、检查过时的 issues 和 pull requests、手动触发的简单 workflow 等。
Pages（页面）：如部署 HTML 静态文件、打包 Jekyll 站点、部署 Astro 站点、打包 Hugo 站点、打包 NuxtJS 站点、打包 Next.js 站点等。

如果你选择 Continuous integration（持续集成）模板中的 Node.js 工作流，来通过 npm 构建和测试 Node.js 项目，点击对应的 Configure 按钮，即可获得以下工作流文件模板内容：




name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x, 22.x]
        

    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
    - run: npm test

你可以在 workflow 编写页面的右侧，点击 Documentation（文档）选项卡，查看编写规则，并对文件进行适当修改。

如果这些模板还是无法满足你的需求，你还能在 workflow 编写页面的右侧点击 Marketplace（市场）选项卡，用关键字搜索别人上传的 GitHub Actions 脚本，直接复用即可。

比如我要操作的是一个用 Vite 打包的前端项目，并且还想要将打包产物部署到 GitHub Pages，通过搜索 vite 可以找到一个叫做 Vite Github Pages Deployer 的 Actions，完美解决我的需求，点击 View full Marketplace listing 可以查看对应用法详情。

2.3 编写并完善 Actions 文件

以下是 Vite Github Pages Deployer 的示例 workflow：

在此路径创建一个操作文件：./.github/workflows/vite-github-pages-deploy.yml。因此，本质上是.github在项目根目录创建一个文件夹，然后yml在其中创建一个文件。
复制下面的代码并将其粘贴到您刚刚创建的操作中，然后保存。
完成。下次推送到master分支时，或者下次从操作选项卡手动运行时，此操作将运行，并且您的项目将部署到 github 页面。

name: Vite Github Pages Deploy

on:
  
  push:
    branches: ["master", "main"]
  
  workflow_dispatch:


permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  
  build:
    runs-on: ubuntu-latest
    environment:
      name: demo
      url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Vite Github Pages Deployer
        uses: skywarth/vite-github-pages-deployer@master
        id: deploy_to_pages

以下是其部分可选的输入参数：

- name: Vite Github Pages Deployer
  
  
  uses: skywarth/vite-github-pages-deployer@v1.4.0
  with:
    
    public_base_path: 
    
    build_path: 
    
    install_phase_node_env: 
    
    build_phase_node_env: 
    
    package_manager: 
    
    artifact_name: 
    
    debug_mode:

根据我要操作的 visionOS 仓库情况对示例 workflow 进行适当修改，并添加一些可选参数，即可得到：




name: Deploy visionOS site to Github Pages


on:
  
  push:
    branches: ["main"]
  
  workflow_dispatch:


permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false


jobs:
  
  
  build:
  	
    runs-on: ubuntu-latest
    environment:
    	
      name: demo
      url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Vite Github Pages Deployer
        uses: skywarth/vite-github-pages-deployer@v1.4.0
        id: deploy_to_pages
        with:
        	
    			package_manager:

上面内容就是我要在 .github/workflows/ 目录下要创建的 workflow 文件内容，即 .yml 为后缀的文件。

该文件命名没有要求，可以叫 vite-github-pages-deploy.yml、deploy.yml、vitejs.yml 等等，只要是保证以 .yml 为后缀即可。GitHub 只要发现 .github/workflows 目录下里面有 .yml 文件，就会自动运行^[4]。

2.4 在 Vite 中设置正确的 base

这是因为项目在部署后（以 visionOS 仓库为例），GitHub Pages 的访问地址会是 https://barry-flynn.github.io/visionOS

也就是说，不是部署到域名根目录下的，所以要在 vite.config.js 中设置正确的 base，使得页面引用静态资源时不会报错^[5-6]。

根据 Vite 文档所言，你可以设置为绝对路径（例如 /visionOS/），也可以设置为 ./ 相对路径。

03 补充 Vite 官方工作流程样本

文章写了一大半了，才发现 Vite 官方文档中也提供了提供了一个安装依赖项和使用 npm 构建的工作流程样本，请见部署静态站点：GitHub Pages


name: Deploy static content to Pages

on:
  
  push:
    branches: ['main']

  
  workflow_dispatch:


permissions:
  contents: read
  pages: write
  id-token: write


concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

当然，由于我使用的是 pnpm 管理的依赖，所以需要稍加修改才能用^[8-10]：




name: Deploy static content to Pages

on:
  
  push:
    branches: ['main']

  
  workflow_dispatch:


permissions:
  contents: read
  pages: write
  id-token: write


concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm run build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          
          path: './dist'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4