GitHub Actions 自动构建并部署 Cloudflare Workers 实现思路

Warning

这个项目在 Cloudflare Workers 上构建时可能会翻车。Astro 构建过程依赖 sharp（图片处理）和一些 Node.js 原生模块，Cloudflare Workers 的构建环境对这些支持有限。如果你在 Workers 上构建失败，别慌，这是正常操作。解决方案是：在 GitHub Actions 里构建好，只把产物丢过去，让 Workers 只管托管静态文件，别让它干重活。

为什么要搞这个#

每次手动构建、再部署，累不累啊？反正我累了。目标是：推送代码到 master 分支后，GitHub Actions 自动帮你搞定三件事：

构建 Astro 项目（让它在 CI 里卷）
把构建产物推送到 build 分支（留个备份）
部署到 Cloudflare Workers（上线，收工）

一条龙服务，你只需要 git push，剩下的交给机器人。

整体流程#

1
push master → checkout → 安装依赖 → pnpm build → 推送 dist 到 build 分支 → wrangler deploy

实现思路#

1. 触发条件#

监听 master 分支的 push 事件，同时支持手动触发（workflow_dispatch）。手动触发的好处是：万一自动部署翻车了，你可以点一下重试，不用再 push 一个空提交。

1
on:
2
  push:
3
    branches: [master]
4
  workflow_dispatch:

2. 环境准备#

GitHub Actions 的 Ubuntu 镜像里没有 pnpm，得自己装。顺序有讲究：先装 pnpm，再装 Node.js，这样 Node.js 的缓存机制才能识别 pnpm。搞反了缓存就废了。

1
- name: Setup pnpm
2
  uses: pnpm/action-setup@v4
3
  with:
4
    version: 9.14.4
5

6
- name: Setup Node.js
7
  uses: actions/setup-node@v4
8
  with:
9
    node-version: '24'
10
    cache: 'pnpm'  # 必须在 pnpm 安装之后

3. 构建项目#

pnpm run build 其实是个三连：先生成图标，再用 Astro 构建，最后用 Pagefind 做全文搜索索引。这三步缺一不可，少了哪个搜索功能都会出问题。

1
- name: Install Dependencies
2
  run: pnpm install --frozen-lockfile
3

4
- name: Build
5
  run: pnpm run build

4. 推送到 build 分支#

用 peaceiris/actions-gh-pages 这个 action，把 dist/ 目录的内容推到 build 分支。它每次都会暴力覆盖，不会保留历史。不过也没关系，反正构建产物每次都一样。

1
- name: Push to build branch
2
  uses: peaceiris/actions-gh-pages@v4
3
  with:
4
    github_token: ${{ secrets.GITHUB_TOKEN }}
5
    publish_dir: ./dist
6
    publish_branch: build

5. 部署到 Cloudflare Workers#

最后一步，用 wrangler deploy 把构建好的静态文件丢到 Workers 上。这一步需要两个 secrets：API Token 和 Account ID，没这俩东西.wrangler 连不上 Cloudflare。

1
- name: Deploy to Cloudflare Workers
2
  run: npx wrangler deploy
3
  env:
4
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
5
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

完整源码#

1
# 构建项目并将产物推送到 build 分支，然后部署到 Cloudflare Workers
2
name: Build to Branch
3

4
# 当推送到 master 分支时触发，也支持手动触发
5
on:
6
  push:
7
    branches: [master]
8
  workflow_dispatch:
9

10
# 需要写入权限来推送 build 分支
11
permissions:
12
  contents: write
13

14
# 同一时间只运行一个构建任务，取消正在运行的旧任务
15
concurrency:
16
  group: build
17
  cancel-in-progress: true
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      # 检出代码
24
      - name: Checkout
25
        uses: actions/checkout@v4
26

27
      # 安装 pnpm 包管理器
28
      - name: Setup pnpm
29
        uses: pnpm/action-setup@v4
30
        with:
31
          version: 9.14.4
32

33
      # 安装 Node.js 并配置 pnpm 缓存
34
      - name: Setup Node.js
35
        uses: actions/setup-node@v4
36
        with:
37
          node-version: '24'
38
          cache: 'pnpm'
39

40
      # 安装项目依赖
41
      - name: Install Dependencies
42
        run: pnpm install --frozen-lockfile
43

44
      # 构建项目：生成图标 → Astro 构建 → Pagefind 索引
45
      - name: Build
46
        run: pnpm run build
47

48
      # 推送 dist 目录到 build 分支
49
      - name: Push to build branch
50
        uses: peaceiris/actions-gh-pages@v4
51
        with:
52
          github_token: ${{ secrets.GITHUB_TOKEN }}
53
          publish_dir: ./dist
54
          publish_branch: build
55

56
      # 使用 wrangler CLI 部署到 Cloudflare Workers
57
      - name: Deploy to Cloudflare Workers
58
        run: npx wrangler deploy
59
        env:
60
          # Cloudflare API Token，需要 Edit Cloudflare Workers 权限
61
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
62
          # Cloudflare 账户 ID，在 Dashboard 右侧栏可见
63
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

需要配置的 Secrets#

在 GitHub 仓库 Settings → Secrets and variables → Actions 里加两个 secret，不加的话 workflow 会直接报错退出。

Secret	说明	获取方式
`CLOUDFLARE_API_TOKEN`	API 令牌	Cloudflare Dashboard → My Profile → API Tokens → Create Token
`CLOUDFLARE_ACCOUNT_ID`	账户 ID	Cloudflare Dashboard 右侧栏

API Token 要选 “Edit Cloudflare Workers” 模板，这个模板包含 Workers 脚本编辑权限，部署够用了。

注意事项#

--frozen-lockfile 是个好东西，确保 CI 里不会偷偷给你更新依赖版本，避免”我本地能跑线上挂了”的经典剧情
concurrency 配置能避免同时跑多个构建任务，省点 CI 分钟数
wrangler deploy 会老老实实读取仓库根目录的 wrangler.toml，所以记得把这个文件提交上去
build 分支只包含 dist/ 的内容，源码不会泄露，放心用

音乐

音乐