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

Tue, 26 Aug 2025 00:00:00 GMT

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

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

每次发布新版本都像在走钢丝：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 工具：

npm install wrangler --save-dev

2. 配置你的 Worker

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

创建 `wrangler.jsonc` 配置文件

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

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

创建 Worker 脚本 `index.ts`

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

export default {
  async fetch(request, env): Promise<Response> {
    const url = new URL(request.url);
    
    // 预留 API 路由，方便未来扩展
    // 比如添加访问统计、留言板等功能
    if (url.pathname.startsWith("/api/")) {
      // 现在先返回个友好的提示
      return new Response("API 功能开发中，敬请期待! 🚧");
    }
    
    // 其他请求都交给静态资源处理
    // Workers 会自动处理缓存、压缩等优化
    return env.ASSETS.fetch(request);
  },
} satisfies ExportedHandler<Env>;

3. 获取 API Token

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

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

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

4. 首次手动部署

# 构建你的项目
npm run build

# 部署到 Workers
npx wrangler deploy

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

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

第二步：绑定自定义域名

1. 把域名dns设置为 Cloudflare

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

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

2. 配置 Worker 路由

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

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

{
...
"route": {
    "pattern": "example.org/*",
    "zone_name": "example.org"
  },
...
}

第三步：GitHub Actions 自动化部署

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

1. 创建 GitHub Actions 工作流

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

name: 自动部署到 Cloudflare Workers 🚀

on:
  push:
    branches:
      - main  # 监听 main 分支的推送
  pull_request:
    branches:
      - main  # PR 时也可以预览部署

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

    steps:
      # 检出代码
      - name: 📥 拉取代码
        uses: actions/checkout@v4

      # 设置 Node.js 环境
      - name: 📦 配置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'  # 缓存依赖，加速构建
          
      # 安装依赖
      - name: 🔧 安装依赖
        run: npm ci  # 使用 ci 而不是 install，更快更稳定

      # 构建项目
      - name: 🏗️ 构建项目
        run: npm run build

      # 部署到 Workers
      - name: 🚀 部署到 Cloudflare
        uses: cloudflare/wrangler-action@v3
        with:
          wranglerVersion: '4.33.0'
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          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 中配置多个环境：

{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2024-07-12",
  "workers_dev": false,
  "route": {
    "pattern": "example.org/*",
    "zone_name": "example.org"
  },
  "kv_namespaces": [
    {
      "binding": "<MY_NAMESPACE>",
      "id": "<KV_ID>"
    }
  ],
  // 在这里配置staging环境
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "route": {
        "pattern": "staging.example.org/*",
        "zone_name": "example.org"
      },
      "kv_namespaces": [
        {
          "binding": "<MY_NAMESPACE>",
          "id": "<STAGING_KV_ID>"
        }
      ]
    }
  }
}

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

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

2. 使用 Workers KV 存储

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

{
...
  "kv_namespaces": [
    {
      "binding": "BLOG_DATA",
      "id": "<YOUR_BINDING_ID>"
    }
  ]
...
}

在代码中使用：

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

// 读取数据
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 文档
Wrangler 配置详解
GitHub Actions 文档
https://www.tjsky.net/tutorial/430
https://blog.pljzy.top/posts/astro/基于astro开发的fuwari静态博客模版配置cicd流程/

Maysee's Blog