开始部署

部署方式概览

本项目支持两种部署方式：通过 Cloudflare Dashboard 的可视化部署和通过命令行的快速部署。选择适合您工作流程的方式。

方式一：控制台部署（推荐新手）

1. 创建应用

访问 Cloudflare Dashboard 并导航到 Workers & Pages 页面：

点击 Create an application
选择 Pages 标签
选择 Connect to Git

2. 设置应用配置

2.1. 项目连接设置

选择 Git 提供商：GitHub / GitLab
选择仓库：找到并选择您的项目仓库
选择分支：通常选择 main 或 master 分支

2.2. 构建与部署命令配置

在 Build & deploy commands 部分：

配置项	设置值	说明
Framework preset	`Next.js (Static HTML Export)`	或选择 `None` 手动配置
Build command	留空	OpenNext 会自动处理构建
Deploy command	`pnpm run deploy`	使用 OpenNext 适配器部署
Root directory	`/`	项目根目录

重要提示：

不要使用 next build，因为我们使用 OpenNext 适配器
pnpm run deploy 命令会执行 opennextjs-cloudflare build && opennextjs-cloudflare deploy

3. 环境变量配置

在部署前，必须配置以下构建时环境变量：

3.1. 必需的构建环境变量

# 认证密钥（构建时需要）
BETTER_AUTH_SECRET = "your-auth-secret-here"
 
# 网站 URL（构建时需要）
NEXT_PUBLIC_SITE_URL = "https://your-domain.pages.dev"
 
# 邮件服务（构建时需要）
RESEND_API_KEY = "your-resend-api-key"

3.2. 环境变量配置步骤

在 Cloudflare Dashboard 中找到您的项目
进入 Settings > Environment variables
分别为 Production 和 Preview 环境添加变量
点击 Save 保存配置

3.3. 可选的构建环境变量

# 社交登录（如果启用）
GOOGLE_CLIENT_ID = ""
GOOGLE_CLIENT_SECRET = ""
GITHUB_CLIENT_ID = ""
GITHUB_CLIENT_SECRET = ""
 
# 支付系统（如果启用）
STRIPE_SECRET_KEY = ""
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY = ""
 
# 验证码（如果启用）
TURNSTILE_SECRET_KEY = ""
NEXT_PUBLIC_TURNSTILE_SITE_KEY = ""

4. 部署完成

配置完成后：

点击 Save and Deploy
Cloudflare 会自动构建和部署您的应用
部署完成后，您会获得一个 *.pages.dev 域名

方式二：命令行部署（推荐开发者）

前置要求

确保已完成以下配置：

数据库配置
环境变量配置
数据库开发
本地 Wrangler 已登录：npx wrangler login

开发和部署命令

# 🚀 本地开发（Next.js 开发服务器）
pnpm dev
# 特点：热重载、快速开发、Node.js 运行时
 
# 🔍 本地预览（Cloudflare Workers 运行时）
pnpm preview
# 特点：接近生产环境、Workers 运行时、测试兼容性
 
# 📦 部署到 Cloudflare
pnpm deploy
# 特点：直接部署、版本控制、生产环境

命令详细说明

开发命令 (`pnpm dev`)

# 等价于
next dev --turbopack

运行时：Node.js
用途：日常开发、调试、功能开发
特点：支持热重载、开发工具、快速迭代

预览命令 (`pnpm preview`)

# 等价于
opennextjs-cloudflare build && opennextjs-cloudflare preview

运行时：Cloudflare Workers (workerd)
用途：部署前测试、兼容性验证
特点：真实的生产环境模拟

部署命令 (`pnpm deploy`)

# 等价于
opennextjs-cloudflare build && opennextjs-cloudflare deploy

运行时：Cloudflare Workers (生产环境)
用途：正式部署到 Cloudflare
特点：全球 CDN、边缘计算、自动扩展

部署后配置

1. 自定义域名（可选）

如果您有自定义域名：

在 Cloudflare Dashboard 中进入项目设置
选择 Custom domains
添加您的域名
更新 DNS 记录指向 Cloudflare

2. 更新环境变量

部署后记得更新 NEXT_PUBLIC_SITE_URL：

# 从开发地址
NEXT_PUBLIC_SITE_URL = "http://localhost:3000"
 
# 更新为生产地址
NEXT_PUBLIC_SITE_URL = "https://your-app.pages.dev"
# 或自定义域名
NEXT_PUBLIC_SITE_URL = "https://yourdomain.com"

3. 验证部署

部署完成后，验证以下功能：

✅ 网站正常访问
✅ 数据库连接正常
✅ 认证系统工作
✅ 邮件发送功能
✅ 文件上传功能

常见问题排查

构建失败

# 检查环境变量是否完整
pnpm cf-typegen
 
# 本地测试构建
pnpm preview

运行时错误

# 检查 Cloudflare 绑定
npx wrangler d1 list
npx wrangler kv namespace list
npx wrangler r2 bucket list

环境变量问题

# 重新上传生产环境密钥
npx wrangler secret bulk .env.production

最佳实践

使用预览环境：部署前务必使用 pnpm preview 测试
环境隔离：开发和生产环境使用不同的数据库和密钥
监控部署：关注 Cloudflare Analytics 和错误日志
版本管理：使用 Git 标签标记部署版本
回滚准备：保持代码版本和环境变量的同步

这样就完成了完整的部署流程，您的 Next.js 应用现在运行在 Cloudflare 的全球边缘网络上！

开始部署

On this page