Pages + Full-stack 框架

两种部署形态

2026 起 Cloudflare 推荐走 Workers + Static Assets——但大量现存项目还在 Pages 上,两种都要懂。

Next.js on Cloudflare

官方推荐 @opennextjs/cloudflare,把 Next.js 构建产物适配到 Workers。

npm create cloudflare@latest my-app -- --framework=next
cd my-app
npm run preview   # 本地用 wrangler 跑,看到 Workers 实际行为
npm run deploy

# wrangler.jsonc 示例
{
  "name": "my-next-app",
  "main": ".open-next/worker.js",
  "compatibility_date": "2026-05-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": { "directory": ".open-next/assets", "binding": "ASSETS" },
  "d1_databases": [{ "binding": "DB", "database_name": "prod", "database_id": "..." }],
  "r2_buckets": [{ "binding": "ASSETS_BUCKET", "bucket_name": "..." }]
}

// app/api/users/route.ts — Next.js Route Handler 里直接用 bindings
import { getRequestContext } from '@opennextjs/cloudflare';

export async function GET() {
  const { env } = getRequestContext();
  const { results } = await env.DB.prepare('SELECT * FROM users LIMIT 10').all();
  return Response.json(results);
}

SvelteKit on Cloudflare

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

export default {
  kit: { adapter: adapter() },
};

// src/routes/api/users/+server.ts
export async function GET({ platform }) {
  const r = await platform.env.DB.prepare('SELECT * FROM users').all();
  return new Response(JSON.stringify(r.results));
}

Remix / Astro

官方 @remix-run/cloudflare 和 @astrojs/cloudflare adapter,流程一致:

1. npm create cloudflare -- --framework=remix 或 astro
2. 本地 npm run dev(Vite 模式)或 npm run preview(wrangler 模式)
3. npm run deploy → 几十秒后全球上线

Functions(老 Pages 模式)

老 Pages 项目里 functions/ 目录,文件系统路由:

functions/
├── api/
│   ├── users/
│   │   └── [id].ts          ← GET /api/users/42
│   └── index.ts             ← GET /api/
└── _middleware.ts           ← 所有路由前置中间件

// functions/api/users/[id].ts
interface Env { DB: D1Database }

export const onRequestGet: PagesFunction<Env> = async (ctx) => {
  const id = ctx.params.id;
  const r = await ctx.env.DB.prepare('SELECT * FROM users WHERE id=?').bind(id).first();
  return r ? Response.json(r) : new Response('404', { status: 404 });
};

Preview 环境

每次 PR 自动部署一个独立 URL <pr-id>.my-app.pages.dev,和生产完全隔离但共享 Bindings 配置。设计/产品 review 直接点链接看效果。

自定义域名与 SSL

1. Pages Dashboard → Custom Domains → 添加 www.example.com
2. 域名需要在 Cloudflare 托管,DNS 自动配置
3. SSL 证书自动签发,强制 HTTPS

构建配置

框架	Build command	Output directory
Next.js	npx opennextjs-cloudflare build	.open-next/worker.js
SvelteKit	npm run build	.svelte-kit/cloudflare
Remix	npm run build	build/client
Astro	npm run build	dist
Vite SPA	npm run build	dist

从 Vercel / Netlify 迁移

陷阱与诊断

本章小结