Mioyui's Blog

Appearance

使用 GitHub Actions 部署 VitePress 项目到 Cloudflare Pages ​

本文档总结了将 VitePress（或其他静态站点）项目通过 GitHub Actions 自动部署到 Cloudflare Pages 的完整流程，并包含了常见错误的解决方法。

总览图 ​

1. 前提条件 ​

  • 项目已托管在 GitHub 仓库中
  • 域名已接入 Cloudflare（可选，用于自定义域名）
  • 本地已安装 pnpm（根据 package.json 的 packageManager 字段）

2. Cloudflare 侧准备 ​

2.1 创建 API 令牌 ​

  1. 登录 Cloudflare 仪表板
  2. 点击右上角头像 → 我的个人资料 → API 令牌
  3. 点击 创建令牌 → 选择模板 编辑 Cloudflare Pages（或自定义）
  4. 设置权限：
    • 账户 → Cloudflare Pages → 编辑
    • 账户 → 账户设置 → 读取（可选）
  5. 账户资源：选择你的账户
  6. 区域资源：选择 所有区域（或包含你域名的区域）
  7. 点击 继续至摘要 → 创建令牌
  8. 复制并保存令牌（只显示一次）

2.2 获取账户 ID ​

在 Cloudflare 仪表板右侧找到 账户 ID（一串字符），保存备用。

3. GitHub 仓库配置 ​

3.1 添加 Secrets ​

进入仓库 → Settings → Secrets and variables → Actions → 添加以下两个 Secret：

NameValue
CLOUDFLARE_API_TOKEN上一步生成的 API 令牌
CLOUDFLARE_ACCOUNT_ID你的 Cloudflare 账户 ID

3.2 设置 Actions 权限 ​

进入仓库 → Settings → Actions → General → Workflow permissions，选择 Read and write permissions。

4. 创建 GitHub Actions 工作流 ​

在项目根目录创建 .github/workflows/deploy-pages.yml，内容如下：

yaml
name: Deploy to Cloudflare Pages

# 关键：给 GITHUB_TOKEN 添加写部署状态的权限
permissions:
  contents: read
  deployments: write

on:
  push:
    branches: [ main ]   # 当推送到 main 分支时触发

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 安装 pnpm（必须，因为 runner 默认没有 pnpm）
      - uses: pnpm/action-setup@v4
        with:
          version: 10   # 与 package.json 中的 packageManager 版本保持一致

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile   # 使用锁文件精确安装

      - name: Build project
        run: pnpm vitepress build   # VitePress 构建命令，按需修改

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-blog                # 替换为你的 Pages 项目名
          directory: ./.vitepress/dist        # 构建输出目录
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

5 提交并触发部署 ​

bash
    git add .github/workflows/deploy-pages.yml
    git commit -m "Add CI/CD for Cloudflare Pages"
    git push origin main

推送后，进入 GitHub 仓库的 Actions 标签页即可查看部署进度。

6 常见错误及解决方法 ​

6.1 Error: Dependencies lock file is not found ​

  • 原因：工作流使用了 npm ci，但项目没有 package-lock.json。
  • 解决：改用 pnpm 并提交 pnpm-lock.yaml（或改用 npm install）。

6.2 Unable to locate executable file: pnpm ​

  • 原因：没有安装 pnpm。
  • 解决：在工作流中添加 pnpm/action-setup 步骤。

6.3 Multiple versions of pnpm specified ​

  • 原因：pnpm/action-setup 中指定的版本与 package.json 中的 packageManager 字段冲突。
  • 解决：使两者版本一致（例如都写 10）。

6.4 Cloudflare API returned 401 ​

  • 原因：API Token 无效、过期或权限不足。
  • 解决：重新生成 Token，确保具有 Cloudflare Pages → Edit 权限，并正确设置 Secret。

6.5 Resource not accessible by integration (403) ​

  • 原因：默认的 GITHUB_TOKEN 没有 deployments:write 权限。
  • 解决：在工作流顶层添加 permissions: { deployments: write }。

6.6 Node.js 20 deprecation warning ​

  • 状态：仅为警告，不影响当前运行。
  • 长期解决：未来将 Actions 版本升级到支持 Node.js 24 的版本（如 v5），或设置环境变量 FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true。

7. 验证部署 ​

  • 在 Cloudflare Pages 控制台查看部署状态
  • 访问你的自定义域名（需在 Pages 项目设置中绑定）。
  • GitHub 仓库的提交页面也会显示部署状态和链接。

8. 总结 ​

通过上述配置，每次 git push 到 main 分支都会自动触发以下流程：

  1. 安装 pnpm 和 Node.js
  2. 使用锁文件安装依赖
  3. 构建静态站点
  4. 上传到 Cloudflare Pages
  5. 在 GitHub 中记录部署状态

整个过程无需手动干预，实现了完全的自动化部署。