前端如何利用 GitHub Actions 自动构建并发布到 GitHub Pages？

🚀 自动部署到 GitHub Pages

为让每次推送都能自动更新静态站点，我们在仓库中添加了一个专门的 workflow：.github/workflow/deploy.yml

该文件定义了两个阶段 —— build（构建）和 deploy（部署），触发条件为向 main 分支的推送或手动触发。

name: Deploy to GitHub Pages

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

🔐 权限

为了让 Action 能读取仓库、写入 Pages 内容，并生成必要的令牌，配置了如下权限：

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

id-token 在后续调用 Azure/OIDC 等服务时常用，这里留作最佳实践。

⚙️ 并发控制

避免同一个分支同时存在多个部署队列，使用：

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

这样新推送不会取消正在进行的构建，保持记录完整。

🛠️ 构建阶段

  build:
    runs-on: ubuntu-latest
    steps:
      - name: 📥 Checkout 代码
        uses: actions/checkout@v4

      - name: 📦 安装 pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: 🔧 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"

      - name: 📚 安装依赖
        run: pnpm install --no-frozen-lockfile

      - name: 🏗️ 构建项目
        run: pnpm run build

      - name: 📤 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: "./dist"

在 build 任务中，Action 会在最新的 Ubuntu runner 上依次执行：

1. Checkout 代码（actions/checkout@v4）
2. 安装 pnpm（pnpm/action-setup@v2，指定版本 8）
3. 设置 Node.js（actions/setup-node@v4，使用 Node 20 并缓存 pnpm 包）
4. 安装依赖：pnpm install --no-frozen-lockfile
5. 运行构建：pnpm run build
6. 上传构建产物：使用 actions/upload-pages-artifact@v3 将 ./dist 文件夹打包为页面部署工件

这一阶段相当于在本地执行 pnpm install && pnpm run build，只不过由 GitHub 的服务器完成，并将结果保存给下游步骤。

📦 部署阶段

构建完成后，deploy 任务会被触发（它声明了 needs: build）：

deploy:
  runs-on: ubuntu-latest
  needs: build
  permissions:
    pages: write
    id-token: write
  steps:
    - name: 🚀 部署到 GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

actions/deploy-pages 会自动获取上一步通过 artifact 上传的 dist 目录，并将其发布到仓库的 GitHub Pages 站点。默认配置下，页面地址为：

https://???.github.io/???/ （也可以在仓库 Settings → Pages 中查看或自定义域名）

🎯 手动触发与调试

该 workflow 支持 workflow_dispatch，意味着可以在“Actions”页手动点击 Run workflow 来触发一次部署，用于测试或紧急修复。

如果构建步骤失败，GitHub 会在 Actions 页面显示日志，方便定位：

• 是否是依赖问题？
• 构建命令是否报错？
• dist 目录是否包含正确的输出？

💡 小贴士

• 自定义构建命令：若后续改用其它构建工具（如 Vite、Vue CLI），只需调整 build 步骤中的命令。
• 分支策略：当前仅对 main 分支部署；若需要发版本分支或预览，可复制定义并修改触发条件。

---

✍️ 总结

通过这套 GitHub Actions 流程，项目实现了零维护的静态站点部署：

1. 开发者只需向 main 推送代码；
2. GitHub 运行构建、缓存依赖、生成 dist；
3. 成品自动发布到 Pages；
4. 用户立即在浏览器访问最新版。