Next.js 跑在 Cloudflare Workers 上

VibeShip 是 Next.js App Router 应用。OpenNext 把服务端构建转换成 Cloudflare Worker；静态资源由 Worker 的 assets binding 提供。D1 保存账号、订阅、积分以及其他产品状态。

配置好后，Worker 还带有 Email sending binding，用于登录码和联系表单流程。自定义域名和路由在 `wrangler.jsonc` 中；observability 已开启，便于构建看似正常但请求失败时排查。

先 `npm ci` 安装锁定依赖，运行 `npm run doctor` 查看配置是否存在，应用 D1 migrations，再用 `npm run cf:build` 构建并部署 Worker。仓库的 CI workflow 展示了同样顺序，并注入生产变量与 secret。

部署会把一个 Worker 版本上传，但不证明用户旅程可用。要在真实域名上验证登录、test billing 流程、D1 页面与 AI 端点。预览构建和 live 构建是不同模式；不要拿预览成功当作生产 secret 已接通的证据。

• `npm ci`：安装锁定依赖。
• `npm run doctor`：检查配置存在，不打印 secret。
• D1 migrations：新版本服务前应用增量 schema。
• `npm run cf:build`：生成 OpenNext Worker bundle。
• 部署：Worker、assets、D1、Email 与路由。
• 验证：真实域名上的公开页与 provider 路径。

`wrangler.jsonc` 绑定 Worker 名称、OpenNext 入口、assets、D1、路由和 Email binding。保留应用需要的生产 plain 变量与 secret：`DATABASE_DRIVER=d1`、auth provider、公开站点 URL，以及启用时的 Stripe、NextAuth 与 AI provider 配置。

只带 `DATABASE_DRIVER` 的直接部署可能丢掉其他生产 plain 变量。手动部署前读取现有 Worker 设置并传完整变量集；secret 会跨 Worker 部署保留，但丢失 plain 变量仍可能让路由失败。[上手指南](/docs/getting-started)与[上线验证](/docs/launch-verification)覆盖配置与检查。

Worker runtime 不是完整的 Node.js 服务器。使用已配置的 compatibility flags 和现有 server adapter；不要假设需要无限制文件系统的包能直接工作。D1 migrations 是增量的，应在新版本服务前应用。

Cloudflare 配置不保证第三方 provider 可达。Stripe、AI provider 与邮件都需要各自验证。模板提供明确的部署路径，不声称每个克隆站都已 production-ready。

预览模式用来查看界面，不用来证明客户旅程。它拒绝写入也不扣费；只有 live 模式才会把 D1、Stripe、邮件和 AI provider 放在一起运行。预览页返回 200，不等于生产 secret 已经存在。

在自己的部署中明确区分两种模式：先做预览构建供评审，再做带生产变量与 secret 的 live 构建。部署后要验证真实域名，而不是只看本地构建。

部署前检查 Worker 名称与路由、D1 database id、assets 与 Email binding、plain 变量与 secret；应用待执行迁移，然后构建部署。部署命令要保留 plain 变量；只带 DATABASE_DRIVER 的部署会让一个正常构建看起来坏了。

如果部署后页面失败，先看 Worker 日志和 provider 状态，不要先改页面代码。缺少 D1 binding、未应用迁移、过期 OAuth callback 或缺 provider key 都是配置失败，构建本身无法证明它们正确。