Cloudflare Worker
在 Cloudflare Workers 上使用 OpenNext 与 Hyperdrive 部署 MuseMVP。
本指南指导您如何直接部署本库到 Cloudflare Workers，同时完全不改变本地原本的 Node.js 开发流。
前置条件
- 需要一个带有 Workers 功能的 Cloudflare 账号。
- Cloudflare Worker 需要支付每月5美元的付费计划（Workers Paid）。因为免费计划对单个项目的体积限制为 3MB（Limits · Cloudflare Workers docs），而当前 MuseMVP 项目构建产物通常在 3MB ~ 4MB 之间，超出了免费计划的限制。
您可以通过本地终端和 Wrangler CLI 直接部署应用。按照以下步骤完成配置与发布：
配置流程
设置 Wrangler 配置名称
在 wrangler.jsonc 文件中，设置 name 字段为您想要的工作负载名称（例如 musemvp-demo）：
"name": "musemvp-demo"Worker 名称
Worker 名称在 Cloudflare 上是全局唯一的，不能与其他 Worker 重名。
配置 DATABASE_CONNECTION_STRATEGY
DATABASE_CONNECTION_STRATEGY="hyperdrive_first"运行时策略
设置 DATABASE_CONNECTION_STRATEGY="hyperdrive_first" 确保在边缘运行时，OpenNext 应用使用的是 Hyperdrive 内网绑定而不是低效外部短链接。
获取 PostgreSQL 数据库连接字符串
首先，从 Neon（或其他 PostgreSQL 提供商）获取您的数据库连接字符串。类似如下：
postgresql://neondb_username:npg_password@ep-xxx-bush-xxxx-pooler.ap-xxx-1.xxx.neon.tech/demo-musemvp-com?sslmode=require&channel_binding=require配置 Hyperdrive 绑定数据库
通过以下命令创建 Hyperdrive 加速池（注意将连接字符串替换为您真实的数据库连接）：
npx wrangler hyperdrive create musemvp-demo --connection-string="postgresql://neondb_username:npg_password@ep-xxx-bush-xxxx-pooler.ap-xxx-1.xxx.neon.tech/demo-musemvp-com?sslmode=require&channel_binding=require"创建成功如下截图：
可以去 Cloudflare 上检查是否存在：
禁用 Hyperdrive 查询缓存
请在控制台中编辑刚才创建的 Hyperdrive 资源，禁用查询缓存。
如果留有缓存，会有意想不到的数据延迟等未知问题
创建完成后，终端会自动将返回的资源 ID 填入 wrangler.jsonc 的对应位置：
{
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<YOUR_HYPERDRIVE_ID>",
"localConnectionString": "postgresql://postgres:postgres@localhost:5432/postgres"
}
]
}注意
上述 localConnectionString 需要填入您本地开发环境的数据库连接信息，即便没有也可以用模板自带的字符串，否则在构建的过程中 Cloudflare Worker 会报错。
创建 worker 项目
这会在控制台上创建您的 Worker 项目：
命令提示
- 连接你的 GitHub 仓库
- Project name: 您的 Worker 项目名称
- Builid command: 留空
- Deploy command:
pnpm run deploy
在部署前，请将最新的数据库结构通过迁移脚本应用至远端实例：
pnpm install
pnpm drizzle:migrate执行初始的部署命令：
pnpm run deploy首次构建肯定失败
这个脚本自动会在 Cloudflare 上创建并部署您的 Worker 项目，不过第一次部署会失败，不用担心，因为还有很多环境变量还没设置。
配置环境变量
前往 Cloudflare 控制台的 Worker 项目设置中配置环境变量。
如下是运行时所需环境变量，建议全部配置上去：
运行时环境变量通过命令形式注入
也可以在本地通过如下命令将环境变量批量注入，并且是加密形式。
# 本地开发环境变量
wrangler secret bulk .env
# 生产环境变量
wrangler secret bulk .env.production如下是构建时所需环境变量，配置NEXT_PUBLIC开头的环境变量上去即可：
绑定域名
在 Cloudflare Worker 项目的设置中，添加并绑定您的自定义域名：
待环境变量配置与域名绑定完成后，再次运行 pnpm deploy 重新部署。
就这样！你的应用现在已经成功部署到 Cloudflare Workers，恭喜！🎉
问题排查
绝大部分报错发生于绑定配置错误（Binding）或缺失对应密钥（Secrets）。排查时先看此项。如果在部署或运行过程中遇到问题，可以尝试以下排查步骤：
日志出现 source=database_url
意味着降级了，检查 wrangler.jsonc 确保绑定名是大小写一致的 HYPERDRIVE
第三方 OAuth 回调重定向匹配失败
确保设定的 NEXT_PUBLIC_SITE_URL 域名和当前 Worker 解析的实际域名完全对应
如果在尝试这些步骤后问题依然存在，请深入检查 Cloudflare 日志以获取更多信息。