Cloudflare Workers开发者指南

AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

边缘计算革命已经不再是一个流行语。截至2026年，Cloudflare的全球网络覆盖了超过120个国家的310多个城市，开发者生态系统已经显著成熟。曾经只是Hono和Workers专用应用的小众部署目标，如今已经成为生态系统中几乎所有主流JavaScript框架的一等部署目的地。

如果你一直因为兼容性问题或文档不清晰，而犹豫是否将Next.js、SvelteKit、Nuxt或Astro项目部署到Cloudflare Workers，那么2026年这个借口不再成立。Cloudflare现在原生支持令人印象深刻的框架列表，并且开发者体验已经通过多年的社区反馈和工具改进得到了精炼。

本指南将详细介绍你需要了解的一切——从理解2026年Cloudflare Workers为何重要，到按照正确的操作顺序自信地部署每个受支持的框架。

0、2026年受支持的框架全景

在深入设置之前，以下是截至2026年Cloudflare通过Workers和Pages官方支持部署的完整框架列表：

全栈和元框架： Next.js、Nuxt、SvelteKit、Analog、SolidStart、Qwik、TanStack Start、React Router（前身为Remix）、RedwoodSDK、Waku、Vike

静态和内容导向： Astro、Gatsby、Docusaurus

API和边缘优先： Hono

UI库（带SSR/SSG适配器）： React、Vue、Angular

每个框架都有专用的适配器或一等构建集成。不同框架的部署方式略有差异，本指南涵盖了让任何框架在Cloudflare Workers上运行的正确逻辑顺序。

1、部署之前理解架构

为什么选择Cloudflare Workers而不是传统服务器？

在2026年，关于无服务器的讨论已经从"是否应该使用它？"转变为"哪个边缘平台适合我的工作负载？"Cloudflare Workers在网络边缘运行你的JavaScript，这意味着你的代码在地理上靠近每个用户的数据中心中执行。不存在传统Lambda风格函数所受的冷启动惩罚，因为Workers在V8隔离环境中运行，而不是在容器中。

对你的框架应用的实际影响是显著的：更快的首字节时间（TTFB）、更低的运维开销、无需服务器管理，以及从零开始的定价模型。

然而，权衡在于Workers运行时不是Node.js。它是一个基于标准的JavaScript环境，支持Web平台API——fetch、Request、Response、Streams、crypto等——但不支持每个Node.js内置模块。这就是为什么每个框架的适配器层至关重要。

1.1 适配器的作用

受支持列表中的每个框架要么自带Cloudflare适配器，要么有社区维护的适配器，可以将你的构建输出转换为Workers运行时可以执行的内容。理解这个模型可以在部署过程中避免数小时的困惑。

例如：

• SvelteKit使用 @sveltejs/adapter-cloudflare
• Cloudflare上的Next.js使用基于OpenNext的适配器，现在维护为 @opennextjs/cloudflare
• Nuxt使用 nitro 配合 cloudflare-pages 或 cloudflare-module 预设
• Astro使用 @astrojs/cloudflare
• Analog使用 @analogjs/platform 配合Cloudflare预设

在开始之前，始终验证适配器版本与框架版本的兼容性。适配器版本不匹配是部署失败的最常见原因。

2、前提条件和环境设置

2.1 设置你的Cloudflare账户和Wrangler CLI

一切从这里开始。你需要一个Cloudflare账户和Wrangler CLI——Cloudflare用于管理Workers、Pages、KV、D1、R2等的官方命令行工具。

截至2026年，Wrangler v4是当前的稳定版本。全局安装或作为开发依赖使用：

npm install -g wrangler

使用你的Cloudflare账户认证Wrangler：

wrangler login

这将打开一个浏览器窗口进行OAuth认证。完成后，Wrangler可以访问你的账户、区域和Workers。

验证设置：

wrangler whoami

你应该能看到你的账户名称和账户ID。保留你的账户ID——你将在 wrangler.toml 中引用它。

2.2 理解wrangler.toml

每个Cloudflare Workers项目通过项目根目录下的 wrangler.toml 文件进行配置。这是你的部署配置的唯一真实来源。一个最小示例：

name = "my-app"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
[vars]
ENVIRONMENT = "production"

compatibility_date 字段至关重要。它告诉Workers运行时要暴露哪个版本的平台API。始终使用与你测试环境匹配的日期。nodejs_compat 标志是大多数现代框架所必需的，用于polyfill框架内部依赖的Node.js API。

2.3 Node.js和包管理器要求

确保你的本地开发环境运行的是Node.js 20或更高版本。截至2026年，Cloudflare的工具链已经放弃了对Node.js 18以下版本的支持，许多框架适配器需要Node.js 20的特性。

使用版本管理器以保持一致性：

nvm install 20
nvm use 20

你的包管理器选择——npm、pnpm或yarn——对部署工作流程影响不大，但由于其严格的依赖解析和磁盘效率，pnpm越来越成为Cloudflare生态系统中的标准。

3、框架特定部署——按复杂度排序

3.1 最简单的部署（静态/内容站点）

这个不介绍了。

3.2 全栈SSR框架

Hono

Hono是一个轻量级、极快的Web框架，专为边缘运行时构建。可以说是这个列表中最原生的Cloudflare Workers框架：

npm create hono@latest my-hono-app
cd my-hono-app

选择 cloudflare-workers 作为模板。你的入口点：

import { Hono } from "hono";
const app = new Hono();
app.get("/", (c) => c.text("Hello from the edge, 2026!"));
export default app;

部署：

wrangler deploy

Hono不需要适配器。它是Workers运行时模型的参考实现。

SvelteKit

Cloudflare上的SvelteKit需要官方适配器：

npm install -D @sveltejs/adapter-cloudflare

更新 svelte.config.js：

import adapter from "@sveltejs/adapter-cloudflare";
export default {
  kit: {
    adapter: adapter({
      routes: {
        include: ["/*"],
        exclude: ["<all>"],
      },
    }),
  },
};

构建和部署：

npm run build
wrangler pages deploy .svelte-kit/cloudflare

Nuxt

Nuxt使用Nitro作为其服务器引擎，内置了Cloudflare预设。在 nuxt.config.ts 中：

export default defineNuxtConfig({
  nitro: {
    preset: "cloudflare-pages",
  },
});

构建和部署：

npm run build
wrangler pages deploy .output/public

对于Workers（非Pages）部署，将预设切换为 cloudflare-module。

Angular（带SSR）

Cloudflare上的Angular SSR使用 @angular/ssr 包配合Cloudflare兼容的服务器入口。从Angular 19+开始，Cloudflare适配器可通过以下方式获取：

ng add @angular/ssr --server-routing

配置你的 wrangler.toml 指向SSR构建输出，并确保启用 nodejs_compat。

Qwik

Qwik的city框架开箱即用地包含了Cloudflare适配器：

npm run qwik add cloudflare-pages

这将安装适配器并相应地设置 vite.config.ts。构建：

npm run build
wrangler pages deploy dist

3.3 高级全栈部署

Next.js（通过OpenNext）

Cloudflare上的Next.js是讨论最多、历史上最具挑战性的部署目标。在2026年，@opennextjs/cloudflare 适配器已经显著成熟，支持App Router、Server Actions和部分预渲染。

安装：

npm install @opennextjs/cloudflare

在 package.json 中添加构建脚本：

{
  "scripts": {
    "build:worker": "opennextjs-cloudflare"
  }
}

配置 wrangler.toml 用于你的输出：

name = "my-nextjs-app"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".open-next/assets"
[build]
command = "npm run build:worker"

部署：

npm run build:worker
wrangler pages deploy

注意：并非所有Next.js功能都在Workers运行时上受支持。使用 next/image 的图片优化需要额外配置或委托给Cloudflare Images。在迁移大型生产应用之前，请查看OpenNext Cloudflare兼容性矩阵。

React Router（前身为Remix）

React Router v7（Remix的演进）具有一等Cloudflare支持。使用Cloudflare模板创建新项目：

npx create-react-router@latest --template cloudflare my-app

这将生成一个预配置了Cloudflare适配器的项目。你的 wrangler.toml、worker入口文件和 react-router.config.ts 从一开始就正确设置好了。

构建和部署：

npm run build
wrangler deploy

TanStack Start

TanStack Start是TanStack Router的全栈变体，于2024年底达到稳定版，通过Nitro支持Cloudflare：

在 app.config.ts 中：

import { defineConfig } from "@tanstack/start/config";
export default defineConfig({
  server: {
    preset: "cloudflare-pages",
  },
});

构建和部署：

npm run build
wrangler pages deploy dist

SolidStart

SolidStart是Solid.js的元框架，使用Nitro并原生支持Cloudflare Pages：

npm create solid@latest my-solid-app

在脚手架过程中选择Cloudflare预设，或在 app.config.ts 中手动配置：

import { defineConfig } from "@solidjs/start/config";
export default defineConfig({
  server: {
    preset: "cloudflare-pages",
  },
});

Analog（Angular元框架）

Analog是一个Angular的全栈元框架，类似于Nuxt之于Vue或SvelteKit之于Svelte的关系。它底层使用Nitro：

// vite.config.ts
import analog from "@analogjs/platform";
export default defineConfig({
  plugins: [
    analog({
      nitro: {
        preset: "cloudflare-pages",
      },
    }),
  ],
});

Vike（前身为vite-plugin-ssr）

Vike为你提供了对SSR设置的精细控制。Cloudflare集成通过自定义服务器入口完成：

// server/index.ts
import { renderPage } from "vike/server";
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const pageContextInit = { urlOriginal: request.url };
    const pageContext = await renderPage(pageContextInit);
    if (pageContext.httpResponse === null) return new Response("Not found", { status: 404 });
    return new Response(pageContext.httpResponse.body, {
      headers: { "Content-Type": pageContext.httpResponse.contentType },
    });
  },
};

Waku

Waku是一个为RSC（React Server Components）设计的极简React框架。它有Cloudflare部署路径：

npm create waku@latest my-waku-app
cd my-waku-app
npm run build -- --with-vercel  # 或cloudflare output
wrangler pages deploy dist

请查看Waku官方文档了解确切的构建标志，因为Cloudflare部署输出一直在演进中。

RedwoodSDK

RedwoodSDK（RedwoodJS面向Workers时代的演进）专为Cloudflare Workers构建，集成了D1、KV和R2。脚手架新项目：

npm create rwsdk@latest my-rw-app

生成的项目包含预配置的 wrangler.toml，带有D1数据库绑定、R2存储桶绑定和Worker入口点。

React（基于Vite的SPA）

使用Vite构建的标准React应用作为静态资源包部署到Cloudflare Pages。纯SPA不需要适配器：

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install
npm run build

通过仪表板或CLI将 dist 文件夹部署到Cloudflare Pages：

wrangler pages deploy dist

Vue

使用Vite时与上面的React相同。构建产生静态输出：

npm create vue@latest my-vue-app
cd my-vue-app
npm install
npm run build
wrangler pages deploy dist

Docusaurus

Docusaurus默认生成完全静态的站点。构建后：

npx create-docusaurus@latest my-docs classic
cd my-docs
npm run build
wrangler pages deploy build

Docusaurus的输出文件夹是 build，而不是 dist。在配置Pages项目时注意这个区别。

Gatsby

Gatsby的静态输出也能干净地部署。安装Cloudflare适配器：

npm install gatsby-adapter-cloudflare

在 gatsby-config.js 中配置：

const adapter = require("gatsby-adapter-cloudflare");
module.exports = {
  adapter: adapter(),
};

然后构建和部署：

gatsby build
wrangler pages deploy public

Astro

Astro具有独特的灵活性——它支持静态、SSR和混合渲染。在Cloudflare上实现完整SSR：

npx astro add cloudflare

这将自动安装 @astrojs/cloudflare 并更新你的 astro.config.mjs：

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
export default defineConfig({
  output: "server",
  adapter: cloudflare(),
});

构建和部署：

npm run build
wrangler pages deploy dist

4、生产级关注点

4.1 环境变量和密钥

在生产部署中，永远不要在源文件甚至 wrangler.toml 中硬编码凭据或API密钥。Cloudflare Workers有原生的密钥管理系统。

通过CLI设置密钥：

wrangler secret put DATABASE_URL

这将提示你输入密钥值，该值会被加密并存储在Cloudflare的基础设施中。你可以在Worker中通过 env.DATABASE_URL 访问它。

对于非敏感配置，在 wrangler.toml 中使用 [vars]：

[vars]
APP_ENV = "production"
API_BASE_URL = "https://api.example.com"

4.2 为什么密钥管理在生产中很重要

在Workers环境中，你的代码在数百个边缘节点上运行。如果密钥被提交到仓库或以明文存储在配置文件中，一次泄露就会同时危及所有节点。Cloudflare的加密密钥存储确保你的凭据只在Worker的隔离执行上下文中运行时解密，永远不会暴露在日志或构建产物中。

4.3 绑定：KV、D1、R2和队列

Cloudflare生态系统最强大的方面之一是Workers与Cloudflare存储和数据原语之间的紧密集成。在 wrangler.toml 中配置它们：

[[kv_namespaces]]
binding = "SESSION_STORE"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-app-assets"

这些绑定在运行时被注入到你的Worker的 env 对象中。这是正确的、安全的模式——没有连接字符串，没有TCP连接，没有防火墙规则。只是在同一网络内的原生API调用。

4.4 自定义域名

将自定义域名指向你的Worker或Pages项目：

wrangler pages domain add yourdomain.example.com

或者在Cloudflare仪表板的Workers和Pages下配置，然后在你的域名DNS设置中设置。使用橙色云DNS记录（代理模式）确保流量通过Cloudflare的网络和你的Worker路由。

5、本地开发工作流

Cloudflare提供 wrangler dev 作为本地开发服务器，准确模拟Workers运行时，包括绑定：

wrangler dev

对于Pages项目：

wrangler pages dev

从Wrangler v4开始，本地开发底层使用Miniflare v4，提供了与生产运行时近乎完美的保真度。你甚至可以在开发过程中使用 --remote 标志连接到远程D1数据库和KV命名空间，这对于在不影响生产数据的情况下测试迁移非常有用。

6、结束语

2026年的Cloudflare Workers代表了JavaScript生态系统中最引人注目的部署目标之一。最初作为一个专门的边缘API处理平台，已经发展成为可以以最小摩擦托管几乎所有现代框架的全栈运行时。

流畅部署体验的关键在于理解分层模型：Workers运行时不是Node.js，适配器弥合了这个差距，而 wrangler.toml 是一切的控制面板。按照本指南中描述的复杂度顺序来处理每个框架——从静态站点开始建立信心，然后转向SSR框架，最后处理更加有主见的全栈设置。

原文链接: Deploying Modern JavaScript Frameworks to Cloudflare Workers in 2026: A Complete Developer Guide

汇智网翻译整理，转载请标明出处