> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Cloudflare Workers开发者指南
- URL: https://www.hubwiz.com/blog/cloudflare-workers-developers-guide/
- Published: 2026-06-03T16:18:52.000Z
- Updated: 2026-06-03T16:18:52.000Z
- Description: 本指南将详细介绍你需要了解的一切——从理解2026年Cloudflare Workers为何重要，到按照正确的操作顺序自信地部署每个受支持的框架。
- Author: admin
- Tags: TOOL, CLOUDFLARE WORKERS, #Import 2026-10-14 14:41

边缘计算革命已经不再是一个流行语。截至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` 文件进行配置。这是你的部署配置的唯一真实来源。一个最小示例：

```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` 作为模板。你的入口点：

```ts
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`：

```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` 中：

```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` 中添加构建脚本：

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

```

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

```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` 中：

```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` 中手动配置：

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

```

#### Analog（Angular元框架）

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

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

```

#### Vike（前身为vite-plugin-ssr）

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

```ts
// 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` 中配置：

```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`：

```js
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]`：

```toml
[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` 中配置它们：

```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](https://lalatenduswain.medium.com/deploying-modern-javascript-frameworks-to-cloudflare-workers-in-2026-a-complete-developer-guide-25d33e5b6d4c?ref=hubwiz.com)

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