跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

从 Pages 迁移到 Workers

最后更新 查看 MarkdownAgent 设置

可使用 Cloudflare Workers 部署全栈应用，包括前端静态资产、后端 API 以及服务端渲染（SSR）页面。

与 Pages 一样，Workers 上对静态资产的请求免费，Pages Functions 调用按与 Workers 相同的费率计费，因此可预期类似的成本结构。

与 Pages 不同，Workers 可用功能明显更广（包括 Durable Objects、Cron Triggers 以及更全面的 Observability）。完整列表见本页底部。

迁移

从 Cloudflare Pages 迁移到 Cloudflare Workers 通常较为直接。以下是迁移项目时最常见的步骤。

框架

若 Pages 项目使用热门框架，多数框架已有面向 Cloudflare Workers 的适配器。将 Pages 专用适配器替换为 Workers 等价物，并遵循其提供的指南。

项目配置

若项目尚无 Wrangler 配置文件（wrangler.jsonc、wrangler.json 或 wrangler.toml），请在项目根目录创建。两个必填字段为：

  • name

    设为要部署到的 Worker 名称。可与现有 Pages 项目名称相同，但须符合 Workers 命名限制（例如最大长度）。

  • compatibility_date。

    若已使用 Pages Functions，设为其中配置的相同日期。否则设为当前日期。

构建输出目录

此前在 Pages 中配置「构建输出目录」（在 Wrangler 配置文件或 Cloudflare 仪表板中），Worker 项目现须设置 assets.directory。

此前，使用 Cloudflare Pages：

{
	"name": "my-pages-project",
	"pages_build_output_dir": "./dist/client/"
}
name = "my-pages-project"
pages_build_output_dir = "./dist/client/"

现在，使用 Cloudflare Workers：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"assets": {
		"directory": "./dist/client/"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"

[assets]
directory = "./dist/client/"

提供行为

Pages 会自动尝试判断所部署项目的类型。它会查找 404.html 和 index.html 以判断项目可能是单页应用（SPA），还是应提供自定义 404 页面。

在 Workers 中，为避免误配置，此行为须显式手动设置。

单页应用（SPA）：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "single-page-application"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"

[assets]
directory = "./dist/client/"
not_found_handling = "single-page-application"

自定义 404 页面：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "404-page"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"

[assets]
directory = "./dist/client/"
not_found_handling = "404-page"
忽略资产

Pages 会自动排除部分文件和文件夹不上传为静态资产，例如 node_modules、.DS_Store 和 .git。若也希望 Worker 不上传这些文件，可在项目静态资产目录中创建 .assetsignore 文件。

dist/client/.assetsignoretxt
**/node_modules
**/.DS_Store
**/.git

Pages Functions

全栈框架

若使用由 Pages Functions 驱动的全栈框架，请确保已更新框架以面向 Workers 而非 Pages。

使用「advanced mode」_worker.js 文件的 Pages Functions

若使用带 「advanced mode」_worker.js 文件 的 Pages Functions，须先确保该脚本不会作为静态资产上传。将 _worker.js 移出静态资产目录（推荐），或在静态资产目录创建 .assetsignore 文件并在其中包含 _worker.js。

dist/client/.assetsignoretxt
_worker.js

然后，更新配置文件的 main 字段，指向该 Worker 脚本的位置：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./dist/client/_worker.js", // or some other location if you moved the script out of the static asset directory
	"assets": {
		"directory": "./dist/client/"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./dist/client/_worker.js"

[assets]
directory = "./dist/client/"
使用 functions/ 文件夹的 Pages Functions

若使用 functions/ 文件夹 的 Pages Functions，须先用 wrangler pages functions build 命令将这些函数编译为单个 Worker 脚本。

npx wrangler pages functions build --outdir=./dist/worker/

虽然可随时运行此命令，若希望继续使用基于文件的路由，我们建议考虑其他框架。HonoX ↗ 是常用选项之一。

Worker 脚本编译完成后，可更新配置文件的 main 字段，指向构建输出位置：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./dist/worker/index.js"

[assets]
directory = "./dist/client/"
_routes.json 与 Pages Functions 中间件

若在 Pages 项目中编写了 _routes.json 文件，或在 Pages Functions 中使用了中间件，须仔细配置 Worker 脚本。Pages 默认优先提供 Pages Functions 而非静态资产，_routes.json 与 Pages Functions 中间件可自定义此行为。

Workers 则默认优先提供静态资产而非 Worker 脚本，除非配置了 assets.run_worker_first。例如在执行身份验证或在提供静态资产前记录请求时，需要此选项。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/",
		"run_worker_first": true
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./dist/worker/index.js"

[assets]
directory = "./dist/client/"
run_worker_first = true
从零开始

若愿意，可新建 Worker 脚本并充分利用 Wrangler 与最新运行时功能（例如 WorkerEntrypoint、TypeScript 支持、打包 等）：

./worker/index.jsjs
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request) {
		return new Response("Hello, world!");
	}
}
./worker/index.tsts
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request: Request) {
		return new Response("Hello, world!");
	}
}
{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./worker/index.ts"

[assets]
directory = "./dist/client/"

Assets binding

Pages 自动为 Pages Functions 提供 ASSETS 绑定（binding） 以访问静态资产。在 Workers 中，该绑定名称可自定义，且须手动配置：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./worker/index.ts"

[assets]
directory = "./dist/client/"
binding = "ASSETS"

运行时

若在 Pages 项目中自定义了 placement、compatibility date 或 compatibility flags，可在 Wrangler 配置文件中定义相同设置：

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": ["nodejs_compat"],
	"main": "./worker/index.ts",
	"placement": {
		"mode": "smart"
	},
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]
main = "./worker/index.ts"

[placement]
mode = "smart"

[assets]
directory = "./dist/client/"
binding = "ASSETS"

变量、密钥与绑定（binding）

变量与绑定（binding）可在 Wrangler 配置文件中设置，并在 Worker 环境（env）中可用。密钥可通过 Wrangler 上传，或在 Cloudflare 仪表板中为生产环境与本地开发 .dev.vars定义。

若使用 Workers Builds，请确保在构建环境中配置相关变量。与 Pages 不同，Workers 的运行时与构建时变量并非同一套。

Wrangler 命令

此前使用 wrangler pages dev 和 wrangler pages deploy，现改用 wrangler dev 和 wrangler deploy。此外，若使用 Vite 驱动的框架，新的 Vite 插件 可能提供更简单的开发体验。

构建

若使用 Pages 内置 CI/CD，可先将仓库连接到 Workers Builds，然后禁用 Pages 项目的自动部署，以改用 Workers Builds。

预览环境

Pages 会为每个项目自动创建预览环境，并可独立配置。

在 Workers 中获得类似体验，须：

  1. 确保预览 URL已启用（默认开启）。

    {
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/"
	},
	"preview_urls": true
}
    name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./worker/index.ts"
preview_urls = true

[assets]
directory = "./dist/client/"

  2. 在 Workers Builds 中启用非生产分支构建。

可选地，还可使用 Cloudflare Access 保护这些预览 URL。

标头与重定向

Workers 静态资产原生支持 _headers 与 _redirects 文件。与 Pages 一样，请确保这些文件包含在项目静态资产目录中。

pages.dev

此前 Pages 项目会提供 pages.dev 子域，现可为所有 Worker 项目配置个性化 workers.dev 子域。可在 Cloudflare 仪表板中配置该子域，并在配置文件中使用 workers_dev 选项选择使用。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"main": "./worker/index.ts",
	"workers_dev": true
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./worker/index.ts"
workers_dev = true

自定义域

若域名的 nameserver 由 Cloudflare 管理，与 Pages 一样，可为 Worker 配置自定义域。此外，还可配置路由，仅让 Worker 处理部分路径。

上线

验证 Worker 行为、对开发工作流满意并完成生产流量迁移后，可在 Cloudflare 仪表板或使用 Wrangler 删除 Pages 项目：

npx wrangler pages project delete

使用 AI 编程助手迁移项目

可在首选编程助手（例如 Claude Code、Cursor）中添加以下实验性提示，使项目兼容 Workers：

https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt

还可在编程助手中使用 Cloudflare Documentation MCP server ↗，为构建 Workers 的 LLM 提供更好的上下文；在要求从 Pages 迁移到 Workers 时会包含此提示。

兼容性矩阵

本兼容性矩阵对比 Workers 与 Pages 的功能。除非下文另有说明，Pages 可用的在 Workers 中可用，Workers 可用的在 Pages 中可用。认为列表有遗漏？提交 pull request ↗ 或创建 GitHub issue ↗。

图例
✅：支持
⏳：即将推出
🟡：不支持，有变通方案
❌：不支持

Workers Pages
编写、测试与部署代码
Cloudflare Vite plugin ✅ ❌
Rollbacks ✅ ✅
Gradual Deployments ✅ ❌
Preview URLs ✅ ✅
Testing tools ✅ ✅
Local Development ✅ ✅
Remote Development (--remote) ✅ ❌
Quick Editor in Dashboard ↗ ✅ ❌
静态资产
Early Hints 🟡 1 ✅
Custom HTTP headers for static assets ✅ ✅
Middleware ✅ 2 ✅
Redirects ✅ ✅
Smart Placement ✅ ✅
Serve assets on a path ✅ ❌
Observability（可观测性）
Workers Logs ✅ ❌
Logpush ✅ ❌
Tail Workers ✅ ❌
Real-time logs ✅ ✅
Source Maps ✅ ❌
Runtime APIs & Compute Models
Node.js Compatibility Mode ✅ ✅
Durable Objects ✅ 🟡 3
Cron Triggers ✅ ❌
Bindings（绑定）
AI ✅ ✅
Analytics Engine ✅ ✅
Assets ✅ ✅
Browser Run ✅ ✅
D1 ✅ ✅
Email Workers ✅ ❌
Environment Variables ✅ ✅
Hyperdrive ✅ ✅
Image Resizing ✅ ❌
KV ✅ ✅
mTLS ✅ ✅
Queue Producers ✅ ✅
Queue Consumers ✅ ❌
R2 ✅ ✅
Rate Limiting ✅ ❌
Secrets ✅ ✅
Service bindings ✅ ✅
Vectorize ✅ ✅
Builds (CI/CD)
Monorepos ✅ ✅
Build Watch Paths ✅ ✅
Build Caching ✅ ✅
Deploy Hooks ✅ ✅
Branch Deploy Controls 🟡 4 ✅
Custom Branch Aliases ⏳ ✅
Pages Functions
File-based Routing 🟡 5 ✅
Pages Plugins 🟡 6 ✅
Domain Configuration
Custom domains ✅ ✅
Custom subdomains ✅ ✅
Custom domains outside Cloudflare zones ❌ ✅
Non-root routes ✅ ❌

Footnotes

  1. 开启 zone 设置后，Workers 可使用 Early Hints。Worker 须发送适当的 Link 标头。更多信息请参阅 103 Early Hints 示例。 ↩

  2. 可通过 run_worker_first 选项配置中间件，但按正常 Worker 调用计费。我们计划在未来探索更多相关选项。 ↩

  3. 要在 Cloudflare Pages 项目中使用 Durable Objects，须创建带 Durable Object 的独立 Worker，并在 Production 与 Preview 环境中声明绑定。在 Workers 中使用 Durable Objects 更简单，且为推荐方式。 ↩

  4. Workers Builds 支持非生产分支构建，但可配置程度尚不及 Pages。 ↩

  5. Workers 支持热门框架，其中许多实现基于文件的路由。此外，可使用 Wrangler 将 functions/ 文件夹编译为 Worker，以简化从 Pages 到 Workers 的迁移。 ↩

  6. 如 5 所述，Wrangler 可将 Pages Functions 编译为 Worker。若从零开始，Pages Functions 可实现的一切也可通过向 Worker 添加代码或使用面向相关第三方工具的框架插件实现。 ↩

这篇文档对您有帮助吗？