告别手动部署的苦日子：把你的前端项目丢到 Cloudflare Workers 上

前言：为什么我们都讨厌手动部署？#

还记得上次凌晨两点，你战战兢兢地把代码手动部署到服务器，然后发现网站挂了的经历吗？😱

每次发布新版本都像在走钢丝：npm run build、压缩文件、FTP上传、祈祷不要出错…这一套流程下来，咖啡都凉了三遍。更别提那种”我明明记得上传了新文件啊”的灵魂拷问时刻。

今天，让我们一起摆脱这种石器时代的部署方式，拥抱自动化的美好生活！我将以我的个人主页为例，手把手教你如何将前端项目部署到 Cloudflare Workers，并配置 GitHub Actions 实现推代码即部署的极致体验。

为什么选择 Cloudflare Workers？#

在开始动手之前，让我先安利一下为什么 Cloudflare Workers 值得你花时间学习：

🚀 全球秒级部署：你的网站会被自动分发到全球 300+ 个数据中心，用户访问时自动连接最近的节点
⚡ 零冷启动：不同于传统容器，Workers 使用 V8 Isolate 技术，启动速度快到让你怀疑人生
💰 白嫖党福音：每天 10 万次免费请求，对个人项目来说绰绰有余
🛡️ 自带防护盾：继承了 Cloudflare 的 DDoS 防护和 WAF，黑客看了都要绕道走

第一步：把现有项目搬到 Workers 上#

1. 准备工作#

首先，确保你有一个 Cloudflare 账号（没有的话赶紧注册一个），然后安装 Wrangler CLI 工具：

1
npm install wrangler --save-dev

2. 配置你的 Worker#

对于已有的前端项目，我们需要创建两个关键文件：

创建 `wrangler.jsonc` 配置文件#

1
{
2
  "name": "my-blog", // 项目名
3
  "compatibility_date": "2025-08-01", // 根据这个日期，决定用哪个版本的wrangler运行时环境
4
  "assets": {
5
    "directory": "./dist",  // 静态网站的发布文件夹
6
    "binding": "ASSETS",
7
    "not_found_handling": "404-page"  // for SSG
8
  },
9
  "main": "index.ts",
10
  "observability": {
11
    "enabled": true,
12
    "head_sampling_rate": 1
13
  }
14
}

TIP
如果你的项目是 SPA（单页应用），需要额外配置路由，让所有路径都返回 index.html。具体配置可以参考官方 SPA 指南。

创建 Worker 脚本 `index.ts`#

1
// Worker 的环境接口，告诉 TypeScript 我们有哪些绑定
2
interface Env {
3
  ASSETS: Fetcher;
4
}
5

6
export default {
7
  async fetch(request, env): Promise<Response> {
8
    const url = new URL(request.url);
9

10
    // 预留 API 路由，方便未来扩展
11
    // 比如添加访问统计、留言板等功能
12
    if (url.pathname.startsWith("/api/")) {
13
      // 现在先返回个友好的提示
14
      return new Response("API 功能开发中，敬请期待! 🚧");
15
    }
16

17
    // 其他请求都交给静态资源处理
18
    // Workers 会自动处理缓存、压缩等优化
19
    return env.ASSETS.fetch(request);
20
  },
21
} satisfies ExportedHandler<Env>;

3. 获取 API Token#

部署需要授权，让我们创建一个权限受限的 API Token：

登录 Cloudflare 仪表板
进入左侧管理帐户 → 帐户 API 令牌
点击 创建令牌，选择 编辑 Cloudflare Workers 模板

CAUTION
永远不要把 API Token 提交到代码仓库！这就像把家门钥匙贴在门上一样危险。

4. 首次手动部署#

1
# 构建你的项目
2
npm run build
3

4
# 部署到 Workers
5
npx wrangler deploy
6

7
# 如果遇到网络问题（你懂的）
8
HTTPS_PROXY=http://你的代理地址:端口 npx wrangler deploy

部署成功后，你会获得一个 *.workers.dev 的免费域名。虽然能用，但不够酷对吧？接下来让我们绑定自己的域名！

第二步：绑定自定义域名#

1. 把域名dns设置为 Cloudflare#

如果你的域名在其他服务商那里，配置她的dns：

在 Cloudflare 仪表板点击 加入域
输入你的域名
按照提示修改域名的 DNS 服务器
添加一条 A 记录：www → 2.2.2.2（这是个占位 IP，让代理模式生效）

DNS配置示例

2. 配置 Worker 路由#

在 Worker 的设置页面，找到 触发器 → 自定义域，添加你的域名。

或者更优雅的方式，在 wrangler.jsonc 中配置：

1
{
2
...
3
"route": {
4
    "pattern": "example.org/*",
5
    "zone_name": "example.org"
6
  },
7
...
8
}

第三步：GitHub Actions 自动化部署#

手动部署只是开始，真正的快乐是推代码即部署！

1. 创建 GitHub Actions 工作流#

在项目根目录创建 .github/workflows/deploy.yml：

1
name: 自动部署到 Cloudflare Workers 🚀
2

3
on:
4
  push:
5
    branches:
6
      - main  # 监听 main 分支的推送
7
  pull_request:
8
    branches:
9
      - main  # PR 时也可以预览部署
10

11
jobs:
12
  deploy:
13
    runs-on: ubuntu-latest
14
    name: 构建并部署
15
    timeout-minutes: 10  # 避免任务卡死
16

17
    steps:
18
      # 检出代码
19
      - name: 📥 拉取代码
20
        uses: actions/checkout@v4
21

22
      # 设置 Node.js 环境
23
      - name: 📦 配置 Node.js
24
        uses: actions/setup-node@v4
25
        with:
26
          node-version: '20'
27
          cache: 'npm'  # 缓存依赖，加速构建
28

29
      # 安装依赖
30
      - name: 🔧 安装依赖
31
        run: npm ci  # 使用 ci 而不是 install，更快更稳定
32

33
      # 构建项目
34
      - name: 🏗️ 构建项目
35
        run: npm run build
36

37
      # 部署到 Workers
38
      - name: 🚀 部署到 Cloudflare
39
        uses: cloudflare/wrangler-action@v3
40
        with:
41
          wranglerVersion: '4.33.0'
42
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
43
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
44
          command: deploy

2. 配置 GitHub Secrets#

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中添加：

CLOUDFLARE_API_TOKEN：你之前生成的 API Token
CLOUDFLARE_ACCOUNT_ID：在 Cloudflare 仪表板可以找到

现在，每次你推送代码到 main 分支，GitHub Actions 就会自动帮你部署。去喝杯咖啡，回来就能看到网站更新了！

进阶技巧：让你的部署更专业#

1. 多环境部署#

在 wrangler.jsonc 中配置多个环境：

1
{
2
  "name": "my-worker",
3
  "main": "src/index.js",
4
  "compatibility_date": "2024-07-12",
5
  "workers_dev": false,
6
  "route": {
7
    "pattern": "example.org/*",
8
    "zone_name": "example.org"
9
  },
10
  "kv_namespaces": [
11
    {
12
      "binding": "<MY_NAMESPACE>",
13
      "id": "<KV_ID>"
14
    }
15
  ],
16
  // 在这里配置staging环境
17
  "env": {
18
    "staging": {
19
      "name": "my-worker-staging",
20
      "route": {
21
        "pattern": "staging.example.org/*",
22
        "zone_name": "example.org"
23
      },
24
      "kv_namespaces": [
25
        {
26
          "binding": "<MY_NAMESPACE>",
27
          "id": "<STAGING_KV_ID>"
28
        }
29
      ]
30
    }
31
  }
32
}

然后在 GitHub Actions 中根据分支部署到不同环境：

1
- name: 部署到预发环境
2
  if: github.ref == 'refs/heads/develop'
3
  run: npx wrangler deploy --env staging

2. 使用 Workers KV 存储#

需要存储一些数据？Workers KV 是个不错的选择：

1
{
2
...
3
  "kv_namespaces": [
4
    {
5
      "binding": "BLOG_DATA",
6
      "id": "<YOUR_BINDING_ID>"
7
    }
8
  ]
9
...
10
}

在代码中使用：

1
// 存储访问计数
2
await env.BLOG_DATA.put("visit_count", "12345");
3

4
// 读取数据
5
const count = await env.BLOG_DATA.get("visit_count");

更多关于kv-cache可以参考：https://developers.cloudflare.com/kv/

常见问题排查#

Q: 部署失败，提示认证错误？ A: 检查 API Token 是否正确，以及是否有足够的权限。

Q: 网站显示 404？ A: 确认 wrangler.jsonc 中的 directory 路径是否正确，以及构建产物是否存在。

Q: 如何处理大文件？ A: Workers 有 25MB 的限制，大文件建议使用 R2 对象存储。

参考链接：

前言：为什么我们都讨厌手动部署？#

为什么选择 Cloudflare Workers？#

第一步：把现有项目搬到 Workers 上#

1. 准备工作#

2. 配置你的 Worker#

创建 wrangler.jsonc 配置文件#

创建 Worker 脚本 index.ts#

3. 获取 API Token#

4. 首次手动部署#

第二步：绑定自定义域名#

1. 把域名dns设置为 Cloudflare#

2. 配置 Worker 路由#

第三步：GitHub Actions 自动化部署#

1. 创建 GitHub Actions 工作流#

2. 配置 GitHub Secrets#

进阶技巧：让你的部署更专业#

1. 多环境部署#

2. 使用 Workers KV 存储#

常见问题排查#

创建 `wrangler.jsonc` 配置文件#

创建 Worker 脚本 `index.ts`#