deploy-cf

Cloudflare Pages 上线技能

将 Next.js (App Router) 项目部署到 Cloudflare Pages Edge Runtime，包含完整的预检、构建、部署、域名配置流程。

适用场景

• Next.js App Router 项目部署到 Cloudflare Pages
• 已有 GitHub 仓库，需要上线到 Cloudflare
• 需要为 Cloudflare Pages 配置自定义域名

---

完整流程

Phase 0: 预检（必做）

部署前必须检查以下项目配置，逐项修复：

0.1 wrangler.toml

确认项目根目录存在 wrangler.toml，内容必须包含：

#:schema node_modules/wrangler/config-schema.json

name = "<project-name>"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"

• name：项目名（小写，将作为 <name>.pages.dev 子域名）
• compatibility_flags：必须包含 nodejs_compat，否则运行时 503 错误
• pages_build_output_dir：必须设置，否则 wrangler 不会应用 compatibility_flags

0.2 next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: {
    unoptimized: true,  // Cloudflare Pages 不支持 Next.js 图片优化
  },
  // 注意：不要设置 output: 'export'，@cloudflare/next-on-pages 会处理输出格式
};

export default nextConfig;

0.3 Edge Runtime 声明

所有动态页面和 API 路由必须添加 Edge Runtime 声明：

// app/page.tsx
export const runtime = 'edge';

// app/api/xxx/route.ts
export const runtime = 'edge';

// app/generator/[param]/page.tsx
export const runtime = 'edge';

⚠️ 关键限制（Next.js 15）：

• export const runtime = 'edge' 和 generateStaticParams 不能共存
• 选择 edge runtime 就必须是动态渲染，放弃静态生成
• params 类型变为 Promise<{...}>，需要 await params

// Next.js 15 正确写法
export default async function Page({
  params,
}: {
  params: Promise<{ platform: string }>;
}) {
  const { platform } = await params;
  // ...
}

0.4 依赖版本兼容

依赖	要求	原因
next	>= 14.3.0	@cloudflare/next-on-pages 最低要求
@cloudflare/next-on-pages	最新版	构建适配器
eslint + eslint-config-next	版本匹配	ESLint v9 与 eslint-config-next 不兼容，用 v8

# 安装必要依赖
npm install -D @cloudflare/next-on-pages
# 如有 ESLint 冲突
npm install -D eslint@8 eslint-config-next@14