【GitHub Actions Workflow 实战】从构建到部署的完整指南，从旧版本部署迁移到新版本的完整流程

原创于 2025-07-31 11:00:00 发布 · 1.9k 阅读

CC 4.0 BY-SA版权

文章标签：

GitHub Actions Workflow 实战：从构建到部署的完整指南

GitHub Actions 已成为现代开发中自动化部署的核心工具，尤其对于 GitHub Pages 这类静态站点部署更是如此。本文将通过一个完整案例，带你掌握 GitHub Workflow 的实战流程，解决从旧版本迁移到新版本的常见问题。

基础看我之前文章
https://blog.csdn.net/qq_59344127/article/details/149721196?spm=1011.2415.3001.5331

一、GitHub Workflow 基本流程

GitHub Actions 的核心是通过 workflow 文件定义自动化流程，一个完整的部署流程通常包含两个关键 jobs（任务）：

build 任务：负责拉取代码、安装依赖、构建项目并生成可部署的静态文件
deploy 任务：将构建好的产物部署到 GitHub Pages 等目标环境

这两个任务按顺序执行，deploy 必须等待 build 完成后才能启动，形成"构建→部署"的完整链路。

二、实战案例：构建（`build`）任务详解

以 VuePress 项目部署到 GitHub Pages 为例，build 任务的完整配置如下，我们逐步骤解析其作用：

jobs:
  build:
    runs-on: ubuntu-latest  # 运行环境：GitHub 提供的 Ubuntu 虚拟机
    
    steps:
      # 步骤 1：拉取代码到虚拟机
      - uses: actions/checkout@v4
        # 作用：将当前仓库的代码克隆到运行 workflow 的虚拟机中
        # 为什么必须？虚拟机是全新环境，默认没有你的代码
        
      # 步骤 2：初始化 GitHub Pages 环境
      - name: Configure Pages
        uses: actions/configure-pages@v5
        # 作用：设置 Pages 部署所需的环境变量、权限和缓存路径
        # 新版本部署的核心依赖，没有这一步会导致后续部署失败
        
      # 步骤 3：配置 Node.js 环境
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20  # 指定 Node 版本（建议使用 LTS 版本）
          cache: "npm"      # 缓存 npm 依赖，加速安装过程
          
      # 步骤 4：安装项目依赖
      - name: Install dependencies
        run: npm ci  # 比 npm install 更严格，严格按照 package-lock.json 安装
        
      # 步骤 5：构建项目
      - name: Build project
        run: npm run build  # 执行项目构建命令，生成静态文件
        # 注意：不同项目的构建命令不同，VuePress 通常是 npm run build，React 可能是 npm run build
        
      # 步骤 6：上传构建产物
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs/.vuepress/dist  # 构建产物的输出路径
          # 路径说明：VuePress 默认输出到 docs/.vuepress/dist，其他项目可能是 dist 或 build

关键步骤解析

运行环境选择（runs-on: ubuntu-latest）
GitHub 提供了多种运行环境（Ubuntu、Windows、macOS），其中 ubuntu-latest 是最常用的选择，因其稳定性好且资源充足，适合大多数前端项目构建。
代码拉取（actions/checkout@v4）
这是所有 workflow 的起点，没有这一步，后续的依赖安装和构建都无从谈起。可以理解为"在虚拟机中执行 git clone"的自动化版本。
环境初始化（configure-pages@v5）
新版 GitHub Pages 部署的"必选项"，负责与 GitHub Pages 服务建立连接，设置部署所需的基础配置。旧版本部署可能没有这一步，但新版本必须添加。
依赖管理与构建
- 使用 actions/setup-node 标准化 Node 环境，避免因版本差异导致的构建问题
- npm ci 确保依赖版本一致，减少"本地能跑，CI 失败"的问题
- npm run build 生成静态文件，这是部署的核心产物
产物上传（upload-pages-artifact@v3）
这一步将构建好的静态文件打包为"artifact"（构建产物），供后续的 deploy 任务使用。
❗ 注意：
旧版本常用 upload-artifact@v3，但 GitHub 已明确弃用 v3 版本，需使用 upload-pages-artifact@v3（专为 Pages 优化的版本），避免出现 deprecated version 错误。

三、实战案例：部署（`deploy`）任务详解

构建完成后，需要将产物部署到 GitHub Pages，这就是 deploy 任务的作用：

deploy:
  needs: build  # 依赖关系：必须等待 build 任务完成才能执行
  runs-on: ubuntu-latest
  environment:
    name: github-pages  # 指定部署环境名称（新版 Pages 要求）
    url: ${{ steps.deployment.outputs.page_url }}  # 部署后自动生成访问链接
    
  steps:
    - name: Deploy to GitHub Pages
      uses: actions/deploy-pages@v4  # 官方部署工具
      id: deployment  # 定义 ID 用于获取部署结果

部署任务核心作用

依赖控制（needs: build）
确保部署动作只在构建成功后执行，避免部署失败的产物。
环境配置（environment）
指定部署到 github-pages 环境，这是新版 Pages 部署的安全要求，同时会自动生成部署后的访问链接。
执行部署（deploy-pages@v4）
官方部署工具，自动读取 build 任务上传的 artifact，将其部署到 GitHub Pages 服务。

四、从旧版本部署迁移到新版本的完整流程

如果你的项目之前使用旧版本部署（如基于 gh-pages 分支的部署），迁移到新版 workflow 部署需要以下步骤：

1. 更新仓库 Pages 源设置

进入仓库 → Settings → Pages
在 Source 选项中，选择 GitHub Actions（而非旧版的分支选择）
保存设置后，GitHub 会自动启用新版部署机制

2. 配置 workflow 权限

进入仓库 → Settings → Actions → General
在 Workflow permissions 部分，选择 Read and write permissions（读写权限）
保存设置，确保 workflow 有权限上传 artifact 和部署 Pages

3. 清理旧配置与缓存

删除旧的部署配置（如 .github/workflows 中基于 peaceiris/actions-gh-pages 的文件）

在 workflow 中添加缓存清理步骤（可选，但推荐）：

- name: Clean cache
  run: |
    npm cache clean --force

4. 使用新版 Action 版本

确保所有 Action 都使用最新兼容版本：

actions/checkout@v4
actions/configure-pages@v5
actions/setup-node@v4
actions/upload-pages-artifact@v3
actions/deploy-pages@v4

五、常见问题与解决方案

deprecated version of actions/upload-artifact: v3 错误
- 原因：使用了旧版 upload-artifact@v3
- 解决：替换为 upload-pages-artifact@v3（专为 Pages 设计，兼容 v4 核心）
部署时提示"找不到 artifact"
- 原因：build 任务未正确上传产物或路径错误
- 解决：检查 upload-pages-artifact 的 path 参数是否与实际构建输出路径一致（如 VuePress 是 docs/.vuepress/dist）
configure-pages 必须添加吗？
- 是的！新版部署中，configure-pages 是 deploy-pages 的前置依赖，缺少会直接导致部署失败。