workers-frameworks

Workers 框架集成

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

快速入门：选择框架

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

框架决策树

Need an API only?
  └─ Yes → Hono (fastest, smallest)
  └─ No → Building a full app?
           └─ React → Next.js (OpenNext) or Remix
           └─ Vue → Nuxt
           └─ Svelte → SvelteKit
           └─ Content-heavy → Astro
           └─ Max performance → 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	全部	ESM 中使用 CJS	转换为 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 }>();

// Middleware
app.use('*', logger());
app.use('/api/*', cors());

// Routes
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 - Serving static files
{
  "name": "my-app",
  "main": "src/index.ts",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  }
}

// Serve static with fallback to app
import { Hono } from 'hono';

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

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

// Static assets fallback
app.get('*', async (c) => {
  return c.env.ASSETS.fetch(c.req.raw);
});

export default app;

何时加载参考文档

在以下情况下，为用户加载对应框架的参考文档：

参考文档	加载时机
references/hono.md	构建 API、微服务或轻量级应用
references/remix.md	使用 loaders/actions 构建全栈 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();
// Or via nitro: event.context.cloudflare.env.DB

错误处理模式

// Universal error boundary pattern
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
  );
});

性能提示

1. 打包体积：压缩后控制在 1MB 以内
2. 冷启动：尽量减少顶层代码
3. 流式传输：在可用时使用流式 SSR
4. 缓存：利用 Cache API 和 CDN
5. 代码拆分：为路由使用动态导入

另请参阅

• workers-performance - 优化技巧
• workers-runtime-apis - Workers API 参考
• cloudflare-worker-base - Workers 基础设置