Next.js 部署选型：Cloudflare Pages 与 Vercel 的实测对比与迁移指南

快速答案

• 结论：如果你的应用以静态页面、SSR、ISR 为主，且对成本敏感、追求全球边缘响应速度，Cloudflare Pages 是 Vercel 的有力替代方案；若重度依赖 next/image 自动优化、无缝预览部署等 Vercel 平台特性，则继续留在 Vercel。
• 首要检查项：确认你的 Next.js 版本是否支持 App Router（若使用 next export 会直接构建失败）；检查代码中是否使用了 Node.js 特有 API（如 fs、path），这些在 Workers 运行时不可用。
• 最小迁移配置：安装适配器后，在 wrangler.toml 中配置 name、compatibility_date、pages_build_output_dir 三个必填参数，并将 package.json 的 build 脚本改为 next build && next-on-pages。
• 适用边界：Cloudflare 方案适合独立开发者、小团队、边缘计算场景；不适合需要开箱即用、团队协作要求高、重度依赖 Vercel 生态的项目。

它解决什么问题：成本与冷启动的取舍

Vercel 作为 Next.js 官方推荐的部署平台，提供了无缝的部署体验，但有两个痛点：边缘函数冷启动和成本随用量膨胀。Cloudflare Pages 基于 Workers 边缘运行时，从根本上消除了冷启动问题，同时免费额度极高（每天 10 万次请求），适合对成本敏感的项目。

但代价是：你需要手动处理图像优化、适配 Workers 运行时差异、接受较弱的预览部署体验。这不是一个"零成本"的迁移，而是一个用配置复杂度换取成本和性能的决策。

安装与快速上手

BASH
npm install -D @cloudflare/next-on-pages wrangler

安装完成后，需要创建 wrangler.toml 配置文件，包含三个必填参数：

TOML
name = "my-nextjs-app"
compatibility_date = "2025-07-01"
pages_build_output_dir = ".vercel/output/static"

然后修改 package.json 中的 build 脚本：

JSON
{
  "scripts": {
    "build": "next build && next-on-pages"
  }
}

部署命令：

BASH
npx wrangler pages deploy .vercel/output/static

与 Vercel 的多维对比

关键差异详解

冷启动：Vercel 的边缘函数在请求到达时需要初始化运行时，导致首字节时间（TTFB）延迟。Cloudflare Workers 使用 V8 隔离技术，请求到达时直接执行，无冷启动开销。对于全球分布的用户，Cloudflare 的 300+ 边缘节点能提供更稳定的响应。

图像优化：这是迁移中最容易踩坑的点。Vercel 的 next/image 组件自动调用其图像优化 API，在 Cloudflare 上不会自动工作，直接返回 400 错误。解决方案是使用 @cloudflare/next-on-pages 提供的图像服务，或集成 Cloudflare Images 并配置 CDN 缓存头。

运行时差异：Workers 运行时不完全兼容 Node.js。以下代码在 Cloudflare 上需要重写：

JAVASCRIPT
// 不兼容：req.nextUrl 在 Workers 中不存在
export function middleware(req) {
  const url = req.nextUrl; // 报错：req.nextUrl is not defined
}

// 兼容写法：使用标准 URL API
export function middleware(req) {
  const url = new URL(req.url);
}

生产环境实践与注意事项

平台锁定风险

迁移到 Cloudflare 后，如果使用了 KV、R2、D1 等 Cloudflare 特定服务，未来迁移到其他平台的成本会很高。建议在架构设计时抽象存储层，避免业务代码直接依赖 Cloudflare API。

安全性配置

1. 敏感信息注入：在 wrangler.toml 中不要硬编码 API 密钥，使用环境变量注入：

TOML
# wrangler.toml
[vars]
API_KEY = "your-api-key"  # 不推荐，应使用 Cloudflare 控制台配置

推荐在 Cloudflare 控制台的 Pages 项目设置中配置环境变量，或使用 wrangler secret put 命令。

2. 访问控制：如果应用包含管理后台，配置 WAF 规则限制 IP 访问。

3. 依赖更新：定期更新 compatibility_date 和依赖版本，避免已知安全漏洞。

性能调优

• 使用 Cloudflare 的缓存规则缓存静态资源，减少 Workers 执行次数。
• 对于 ISR 页面，配置合适的 revalidate 时间，平衡实时性和成本。
• 利用 Cloudflare 的 DDoS 防护和 WAF 功能，无需额外配置。

常见报错与排查

1. Build failed: 'next export' is not supported with app router

原因：App Router 不支持 next export，需要改用 next-on-pages 适配器。

解决：

BASH
# 确保已安装适配器
npm install -D @cloudflare/next-on-pages

# 修改 package.json 的 build 脚本
"build": "next build && next-on-pages"

# 确认 wrangler.toml 中 pages_build_output_dir 指向正确目录
pages_build_output_dir = ".vercel/output/static"

2. Middleware error: 'req.nextUrl' is not defined

原因：Workers 运行时与 Vercel Edge 运行时不同，req.nextUrl 不可用。

解决：使用标准 URL API 替代：

JAVASCRIPT
// 错误写法
const url = req.nextUrl.pathname;

// 正确写法
const url = new URL(req.url).pathname;

3. Image optimization not working: next/image returns 400

原因：Cloudflare 上没有内置的图像优化服务。

解决：使用 @cloudflare/next-on-pages 的图像服务，或配置 Cloudflare Images：

JAVASCRIPT
// next.config.js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './cloudflare-loader.js',
  },
};

4. Deploy failed: 'compatibility_date' is required

原因：wrangler.toml 中缺少必填参数。

解决：在配置文件中添加有效的日期：

TOML
compatibility_date = "2025-07-01"

常见问题 FAQ

Q: Cloudflare Pages 和 Vercel 在 Next.js 部署上的核心区别是什么？

A: 核心区别在于运行时和成本。Vercel 提供无缝的 Next.js 体验，但边缘函数有冷启动且成本随用量增长。Cloudflare 基于 Workers 边缘运行时，无冷启动、成本极低，但需要适配和手动配置图像优化等特性。

Q: 迁移到 Cloudflare 后，next/image 如何处理？

A: next/image 在 Cloudflare 上不自动工作，需要手动集成。可以使用 @cloudflare/next-on-pages 的图像服务，或使用 Cloudflare Images 和 CDN 缓存，并配置相应的 loader 和缓存头。

Q: Cloudflare 的预览部署体验如何？

A: Cloudflare 提供类似 Vercel 的预览部署，但体验不如 Vercel 流畅。它支持分支和 PR 预览，但 GitHub 集成和上下文链接不如 Vercel 自动化，可能需要额外配置。

选型建议

选择 Cloudflare Pages 当：

• 项目以静态内容、SSR、ISR 为主，API 路由较少
• 对成本敏感，希望控制预算
• 需要全球边缘响应，且无法接受冷启动
• 愿意投入时间进行配置调优

继续使用 Vercel 当：

• 重度依赖 next/image 自动优化、无缝预览部署
• 团队协作频繁，需要流畅的 PR 预览体验
• 希望开箱即用，不想处理运行时兼容问题
• 项目预算充足，更看重开发效率而非成本

如果你的项目符合 Cloudflare 的适用场景，建议先在一个非核心服务上试点迁移，验证运行时兼容性和性能表现后再全面切换。