在现代 Web 开发中,Next.js 凭借其强大的全栈开发能力备受欢迎。本文将详细介绍如何将 Next.js 应用部署到 Cloudflare Pages,借助 Edge Runtime打造高性能的全球化应用。
一、基础概念
1.1 运行时选择
Next.js 提供两种运行时环境:
• Edge Runtime: 轻量级运行时,适合 Cloudflare Pages
• Node.js Runtime: 完整的 Node.js API 支持
在 Next.js 中，Edge 运行时是一种轻量级的执行环境，基于标准的 Web API，旨在在边缘节点（Edge）上快速处理请求。与传统的 Node.js 运行时 相比，Edge 运行时具有以下特点：
| 特性 | Node.js 运行时 | Edge 运行时 |
| 定义 | 基于 V8 引擎的服务器端 JavaScript 运行时，提供完整的 Node.js API。 | 基于 Web API 的轻量级运行时，适用于边缘计算。 |
| 启动时间 | 相对较长，适合处理复杂任务。 | 启动速度快，适合需要快速响应的场景。 |
| API 支持 | 支持所有 Node.js API 和 npm 包。 | 仅支持标准 Web API，不支持如 fs 等 Node.js 原生模块。 |
| 适用场景 | 需要完整 Node.js 功能的应用，如复杂的服务器端逻辑、文件操作等。 | 需要低延迟响应的应用，如个性化内容渲染、A/B 测试等。 |
| 部署与扩展性 | 需要管理和扩展服务器基础设施，或使用无服务器平台如 Vercel。 | 通过边缘网络部署，具有更高的可扩展性和更低的延迟。 |
| 使用方法 | 默认使用；可在页面或布局文件中导出 runtime 变量来指定。 | 需在页面或布局文件中导出 runtime 变量并设置为 'edge'。 |
| 注意事项 | 启动时间较长，可能不适合需要极低延迟的场景。 | 由于不支持所有 Node.js API，某些 npm 包可能无法正常工作。 |
选择合适的运行时应根据应用的具体需求，权衡性能、功能和开发便利性。
1.2 支持的 Next.js 版本
• 支持 Next.js 13 和 14 的所有次版本
• 定期进行兼容性测试确保稳定性
二、部署步骤详解
2.1 新项目快速开始
如果你要创建新项目,可以使用官方脚手架:
pnpm create cloudflare@latest my-next-app --framework=next2.2 已有项目改造步骤
1) 安装依赖
npm install --save-dev @cloudflare/next-on-pages2) 添加配置文件
在项目根目录创建 wrangler.toml:
name = "my-app"
compatibility_date = "2024-07-29"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"3) 更新 Next.js 配置
修改 next.config.mjs:
import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev';
/** @type {import('next').NextConfig} */
const nextConfig = {};
if (process.env.NODE_ENV === 'development') {
await setupDevPlatform();
}
export default nextConfig;4) 配置服务端路由
所有服务端渲染的路由都需要使用 Edge Runtime:
// app/api/hello/route.js
export const runtime = "edge";
export async function GET() {
return new Response('Hello World');
}5) 更新 package.json
添加必要的脚本命令:
{
"scripts": {
"pages:build": "npx @cloudflare/next-on-pages",
"preview": "npm run pages:build && wrangler pages dev",
"deploy": "npm run pages:build && wrangler pages deploy"
}
}三、高级功能配置
3.1 绑定集成
如果需要使用 Cloudflare 的 KV、R2 等服务,需要配置绑定。
更多关于 Cloudflare 的 KV、R2 等服务的详细 内容请关注后续的全栈开发文章
1. 首先安装类型声明:
npm install --save-dev @cloudflare/workers-types1. 创建类型声明文件
env.d.ts:
interface CloudflareEnv {
MY_KV: KVNamespace;
MY_R2: R2Bucket;
}1. 在代码中使用绑定:
import { getRequestContext } from "@cloudflare/next-on-pages";
export const runtime = "edge";
export async function GET(request) {
const { env } = getRequestContext();
const data = await env.MY_KV.get("key");
return new Response(data);
}3.2 自定义 Worker 入口
如果需要在请求处理前后添加自定义逻辑,可以创建自定义入口点:
import nextOnPagesHandler from "@cloudflare/next-on-pages/fetch-handler";
export default {
async fetch(request, env, ctx) {
// 请求前处理
console.log("收到请求:", request.url);
const response = await nextOnPagesHandler.fetch(request, env, ctx);
// 响应后处理
response.headers.set("X-Custom-Header", "value");
return response;
},
} as ExportedHandler<{ ASSETS: Fetcher }>;3.3 静态资源路由
通过创建 _routes.json 可以自定义静态资源处理:
{
"version": 1,
"exclude": [
"/favicon.ico",
"/static/*"
]
}四、部署和测试
4.1 本地测试
npm run preview4.2 生产部署
npm run deploy更多关于 Next.js的全栈内容请点击下面的合集
