name: workers-frameworks description: Cloudflare Workers 的框架集成。在 Workers 上使用 Hono、Remix、Next.js、Astro、SvelteKit、Qwik 或 Nuxt 构建时使用。涵盖路由、SSR、静态资产和边缘部署。 version: 1.0.0

Workers 框架集成

使用现代框架在 Cloudflare Workers 上构建全栈应用程序。

快速开始：选择您的框架

框架	最适合	SSR	静态	Workers 原生
Hono	API、轻量级应用	✅	✅	✅ 原生
Remix	全栈应用	✅	✅	✅ 适配器
Next.js	React 应用	✅	✅	⚠️ OpenNext
Astro	内容网站	✅	✅	✅ 适配器
SvelteKit	Svelte 应用	✅	✅	✅ 适配器
Qwik	可恢复应用	✅	✅	✅ 适配器
Nuxt	Vue 应用	✅	✅	✅ Nitro

框架决策树

需要仅 API 吗？
  └─ 是 → Hono（最快、最小）
  └─ 否 → 构建全栈应用？
           └─ React → Next.js（OpenNext）或 Remix
           └─ Vue → Nuxt
           └─ Svelte → SvelteKit
           └─ 内容为主 → Astro
           └─ 最大性能 → Qwik

前 10 个框架错误

错误	框架	原因	解决方案
`No matching export "default"`	所有	错误的导出格式	使用 `export default app` 而不是 `module.exports`
`Worker exceeded CPU limit`	Next.js	重度 SSR	使用 ISR，减少捆绑包大小
`Cannot read properties of undefined (reading 'env')`	Remix	缺少上下文	将 `context` 传递给 loader/action
`globalThis is not defined`	所有	Node.js 全局变量	使用 `nodejs_compat` 标志
`Dynamic require not supported`	所有	CJS 在 ESM 中	转换为 ESM 导入
`Response body is locked`	所有	响应体已读取	在读取前克隆响应
`Bindings not available`	所有	缺少 wrangler 配置	在 wrangler.jsonc 中添加绑定
`404 on static assets`	所有	错误的资产配置	在 wrangler.jsonc 中配置 `assets`
`Hydration mismatch`	React/Vue	服务器/客户端不一致	确保渲染一致
`Maximum call stack exceeded`	所有	循环导入	重构模块结构

Hono 快速开始（推荐）

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';

interface Env {
  DB: D1Database;
  KV: KVNamespace;
}

const app = new Hono<{ Bindings: Env }>();

// 中间件
app.use('*', logger());
app.use('/api/*', cors());

// 路由
app.get('/', (c) => c.text('Hello Workers!'));

app.get('/api/users', async (c) => {
  const { results } = await c.env.DB.prepare('SELECT * FROM users').all();
  return c.json(results);
});

app.post('/api/users', async (c) => {
  const { name, email } = await c.req.json();
  await c.env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
    .bind(name, email)
    .run();
  return c.json({ success: true }, 201);
});

export default app;

// wrangler.jsonc
{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-01",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "xxx" }
  ]
}

静态资产配置

// wrangler.jsonc - 提供静态文件
{
  "name": "my-app",
  "main": "src/index.ts",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  }
}

// 使用应用回退提供静态文件
import { Hono } from 'hono';

const app = new Hono<{ Bindings: { ASSETS: Fetcher } }>();

// API 路由
app.get('/api/*', apiHandler);

// 静态资产回退
app.get('*', async (c) => {
  return c.env.ASSETS.fetch(c.req.raw);
});

export default app;

何时加载参考资料

用户需要时加载特定框架参考资料：

参考资料	加载时机
`references/hono.md`	构建 API、微服务或轻量级应用时
`references/remix.md`	使用加载器/操作的全栈 React 应用时
`references/nextjs.md`	通过 OpenNext 在 Workers 上使用 Next.js App Router 时
`references/astro.md`	构建内容网站、博客、文档或营销页面时
`references/sveltekit.md`	在 Workers 上构建 Svelte 应用时
`references/qwik.md`	构建可恢复应用、即时加载时
`references/nuxt.md`	使用 Nitro 构建 Vue 3 应用时

跨框架的通用模式

环境绑定访问

// Hono
app.get('/', (c) => c.env.DB.prepare('...'));

// Remix
export async function loader({ context }) {
  return context.cloudflare.env.DB.prepare('...');
}

// Astro
const db = Astro.locals.runtime.env.DB;

// SvelteKit
export async function load({ platform }) {
  return platform.env.DB.prepare('...');
}

// Nuxt
const { cloudflare } = useRuntimeConfig();
// 或通过 nitro：event.context.cloudflare.env.DB

错误处理模式

// 通用错误边界模式
app.onError((err, c) => {
  console.error(`[${c.req.path}] ${err.message}`);

  if (err instanceof HTTPException) {
    return err.getResponse();
  }

  return c.json(
    { error: 'Internal Server Error' },
    500
  );
});

性能提示

捆绑包大小：保持压缩后小于 1MB
冷启动：最小化顶级代码
流式处理：可用时使用流式 SSR
缓存：利用 Cache API 和 CDN
代码拆分：路由的动态导入

另请参阅

workers-performance - 优化技术
workers-runtime-apis - Workers API 参考
cloudflare-worker-base - 基本 Workers 设置