2025 年如何将静态网站部署到 Cloudflare Workers

Fred· AI Engineer & Developer EducatorOctober 19, 20255 min read

cloudflare deployment workers gatsby devops

**最后测试：**2025 年 10 月 | **Wrangler：**3.x | **Node.js：**20+ | **平台：**macOS/Linux/Windows

如果你一直通过 Cloudflare Pages 的 Git 集成部署，你可能注意到了一条新的弃用消息：Cloudflare 在 2025 年 4 月弃用了 Pages。 他们正在推动所有人转向 Cloudflare Workers。

一开始，这听起来很烦人。Pages 非常简单——连接你的仓库，设置构建命令，完成。Workers？这听起来像你需要编写 serverless 函数并理解边缘计算，是的，如果你不知道从哪里开始，这可能会令人生畏。

好消息是：一旦你理解了工作流程，将静态网站部署到 Workers 是很直接的。 而且你在部署过程中获得了更多控制。

我刚刚将我的 Gatsby 博客从旧的 Pages 流程迁移到 Workers。以下是我学到的一切。

完整的迁移路径

本指南为你提供将静态网站迁移到 Workers 的确切步骤，包括：

可用的代码示例 - 在真实生产网站上测试过
常见陷阱 - 以及如何避免它们
性能比较 - 显示 Workers 更快
成本分析（剧透：对大多数网站仍然免费）

为什么 Cloudflare 终止了 Pages

Cloudflare 的理由很清楚：Workers 是他们统一的边缘计算平台。与其维护两个独立的系统（Pages 用于静态网站，Workers 用于函数），他们正在将一切整合到 Workers 中。

虽然 Cloudflare 可能需要几年时间才能完全退役 Pages 部署，但 Workers 将获得所有新功能并得到积极支持；Pages 不会。

如果你正在开始新项目或迁移现有项目，Workers 是唯一的前进道路。为了强调：我不建议将任何新项目部署到 Cloudflare Pages。

你需要什么

在我们开始之前，确保你有：

一个静态网站（Gatsby、Next.js 静态导出、React 构建、Hugo、Astro）
安装了 Node.js 20+
一个 Cloudflare 账户（免费层级就够了）
Wrangler CLI（我们将安装它）

步骤 1：安装 Wrangler

Wrangler 是 Cloudflare 用于部署到 Workers 的命令行工具。将其添加到你的项目：

npm install -D wrangler

或者如果你更喜欢全局安装：

npm install -g wrangler

我建议将其作为开发依赖项安装在项目中，以便你的团队使用相同的版本。

步骤 2：认证 Wrangler

在你可以部署之前，你需要将 Wrangler 连接到你的 Cloudflare 账户：

npx wrangler login

这会打开你的浏览器并要求你授权 Wrangler。点击"允许"就完成了。

对于 CI/CD，你需要使用 API 令牌（我们稍后会介绍）。

步骤 3：创建 wrangler.toml

Wrangler 需要一个在项目根目录的配置文件。创建 wrangler.toml：

name = "your-project-name"
compatibility_date = "2025-10-19"

# 这告诉 Wrangler 你的静态文件在哪里
pages_build_output_dir = "public"

[site]
bucket = "./public"

关键字段：

name：你的项目名称（成为你的 Workers URL 的一部分）
compatibility_date：锁定你的 Workers 运行时版本
pages_build_output_dir：构建后静态文件的位置
bucket：同样的东西，不同的语法（两者都有效）

对于 Gatsby 网站，输出目录是 public。对于 Next.js，是 out。对于 Create React App，是 build。

步骤 4：构建你的网站

这里没有任何变化。运行你正常的构建命令：

# Gatsby
npm run build

# Next.js（静态导出）
npm run build && npm run export

# Create React App
npm run build

这会在你的输出目录中生成静态文件。

步骤 5：部署到 Workers

这是神奇的命令：

npx wrangler pages deploy public

用你的输出目录替换 public。

第一次部署？ Wrangler 会询问：

✔ 输入你新项目的名称：… your-site-name
✔ 输入生产分支名称：… main

之后，Wrangler 构建并部署你的网站。你将得到一个 URL 像：

https://your-site-name.pages.dev

是的，即使它是通过 Workers 部署的，它仍然使用 .pages.dev 域名。Cloudflare 为静态网站保留了这个命名。

步骤 6：将部署脚本添加到 package.json

每次输入 npx wrangler pages deploy public 很烦人。将脚本添加到你的 package.json：

{
  "scripts": {
    "build": "gatsby build",
    "deploy": "npm run build && wrangler pages deploy public",
    "deploy:prod": "npm run build && wrangler pages deploy public --branch=main"
  }
}

现在部署只需：

npm run deploy

步骤 7：自定义域名设置

你的 .pages.dev URL 可以工作，但你可能想要你自己的域名。

选项 1：通过 Cloudflare 仪表板（最简单）

一旦你的第一次部署成功，添加你的自定义域名：

登录你的 Cloudflare 仪表板 https://dash.cloudflare.com
在左侧边栏，点击 Workers & Pages
找到你的项目（例如 vibe-coding-redo）并点击它
点击顶部的 Custom domains 标签
点击 Set up a custom domain 按钮
输入你的域名（例如 vibecodingwithfred.com）
点击 Continue
如果需要，为 www 子域名添加另一个域名（例如 www.vibecodingwithfred.com）
点击 Activate domain

重要说明：

你的域名必须已经在 Cloudflare DNS 上（如果不是，先将其添加到 Cloudflare）
SSL 证书会自动提供（通常需要 1-2 分钟）
DNS 记录会自动创建
如果域名之前在另一个 Pages/Workers 项目上使用，Cloudflare 会自动移动它

选项 2：通过 Wrangler

你也可以在 wrangler.toml 中配置域名：

name = "your-project-name"
compatibility_date = "2025-10-19"

[[routes]]
pattern = "yourdomain.com"
zone_name = "yourdomain.com"

[[routes]]
pattern = "www.yourdomain.com"
zone_name = "yourdomain.com"

然后运行：

npx wrangler pages deploy public

Wrangler 获取域名配置并应用它。

步骤 8：使用 GitHub Actions 自动部署

旧的 Pages 流程在你推送到 main 时自动部署。我们可以使用 GitHub Actions 重新创建这个。

创建 .github/workflows/deploy.yml：

name: Deploy to Cloudflare Workers

on:
  push:
    branches:
      - main

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=your-project-name

获取你的 Cloudflare 凭据

你需要两样东西：

1. Account ID：

前往 Cloudflare 仪表板
点击 Workers & Pages
你的 Account ID 在右侧边栏

2. API Token：

前往 My Profile → API Tokens
点击 Create Token
使用 "Edit Cloudflare Workers" 模板
复制令牌（你只能看到一次！）

将 Secrets 添加到 GitHub

前往你的仓库 → Settings → Secrets and variables → Actions → New repository secret

添加：

CLOUDFLARE_API_TOKEN：你的 API 令牌
CLOUDFLARE_ACCOUNT_ID：你的账户 ID

现在每次推送到 main 都会自动触发部署。

常见问题和修复

问题 1：依赖冲突

如果你从 Pages 迁移并遇到 npm 错误如：

npm error ERESOLVE could not resolve

在项目根目录创建 .npmrc：

legacy-peer-deps=true

这告诉 npm 忽略对等依赖冲突（旧版 Gatsby 插件常见）。

问题 2：Node 版本不匹配

Workers 默认使用 Node 20+。如果你的项目需要特定版本，锁定它：

创建 .nvmrc：

和 .node-version：

更新 package.json：

{
  "engines": {
    "node": ">=18.0.0 <=20.x"
  }
}

问题 3：构建输出目录错误

如果 Wrangler 找不到你的文件：

✖ No such directory 'public'

检查你的 wrangler.toml 并确保 pages_build_output_dir 与你实际的构建输出匹配。

问题 4：CI/CD 中认证失败

如果 GitHub Actions 失败并出现认证错误，仔细检查：

你的 API 令牌有 Edit Cloudflare Workers 权限
你将 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 都添加为 secrets
令牌没有过期

从旧 Pages 零停机迁移

如果你要从旧的 Pages 设置迁移：

策略 1：部署到新的 Workers 项目

使用不同的项目名称设置 Workers 部署
在 .pages.dev 预览 URL 上测试
准备好后，将你的自定义域名添加到新项目
Cloudflare 自动将域名从旧的移到新的（即时切换）
删除旧的 Pages 项目

策略 2：渐进式切换

保持旧的 Pages 部署运行
使用暂存域名部署到 Workers
彻底测试
更新 DNS 指向 Workers
确认一切正常后弃用 Pages

**推荐：**策略 1 更干净且零停机。

Workers 函数怎么办？

本指南涵盖了静态网站部署，但 Workers 可以做更多。如果你需要 serverless 函数（如 API 端点），你可以添加它们：

创建 functions/api.js：

export async function onRequest(context) {
  return new Response(JSON.stringify({ message: "Hello from Workers!" }), {
    headers: { "Content-Type": "application/json" }
  });
}

使用以下命令部署：

npx wrangler pages deploy public

你的 API 现在在 /api 上线了。

这超出了本指南的范围，但这是 Cloudflare 希望每个人都使用 Workers 的原因之一——你在一个平台上获得静态网站和 serverless 函数。

部署清单

这是你的完整设置清单：

底线

Cloudflare 终止 Pages 并强迫每个人转向 Workers 一开始感觉像是倒退。基于 Git 的自动部署真的很方便。

但一旦你设置了 Wrangler 和 CI/CD，你得到：

完全控制何时以及如何部署
更快的部署（无需等待 Cloudflare 的构建队列）
更好的调试（你可以在部署前本地测试构建）
访问 Workers 功能（函数、KV 存储、边缘逻辑）

初始设置需要 20 分钟。之后，只需 git push，GitHub Actions 处理其余的——与 Pages 相同的体验，但底层有更多能力。

当你准备好为静态网站添加 serverless 函数或边缘逻辑时，你已经在正确的平台上了。

更喜欢更简单的部署？ 如果你主要构建 Next.js 网站并重视零配置部署，Vercel 提供了极好的替代选择，具有自动 Git 集成和慷慨的免费层级限制。

资源

有关于迁移到 Workers 的问题？在评论中或 Twitter 上联系我。我刚刚完成了这个迁移，所以痛苦的记忆还很新鲜。

Fred

AUTHOR

Full-stack developer with 10+ years building production applications. I've been deploying to Cloudflare's edge network since Workers launched in 2017.

About me →More articles →

Need a developer who gets it?

POC builds, vibe-coded fixes, and real engineering. Let's talk.

Hire Me →