部署到 Vercel

Vercel 是 VibeAny Starter 发布验收门禁实际验证过的生产部署路径。受支持的基线使用托管 PostgreSQL 数据库、Better Auth 邮箱密码认证和 Resend。依赖外部服务商的可选能力默认保持关闭，直到你单独完成配置和测试。

deploy:vercel 命令只覆盖经过验证的最小基线。它要求关闭支付、Google One Tap 和 AI 图片生成。更改这些开关前，请先阅读启用支付的部署。

前置条件

• Node.js >=24.0.1 和 npm >=11.3.0
• Vercel 账户，以及专用于当前应用的项目
• 托管 PostgreSQL 连接 URL
• 高强度的 Better Auth 密钥
• Resend API 密钥，以及已验证域名下的发件地址
• 干净的工作区；drizzle/ 下经过审查的 SQL 迁移已提交

部署脚本固定使用 Vercel CLI 54.21.1，因此无需全局安装 CLI。

1. 关联目标项目

在 Starter 根目录运行：

npx --yes vercel@54.21.1 login
npx --yes vercel@54.21.1 link

继续之前，检查生成的 .vercel/project.json，确认其中指向你要部署的项目。.vercel/ 是本地状态，已被 Git 忽略。如果项目或团队不正确，请重新关联；不要继续部署后再寄希望于修正目标。

2. 配置基线环境

把下列值添加到 Vercel 的 Production 环境。三个 URL 变量都应使用最终生产源地址，末尾不要带路径。

把这些 Production 环境变量拉取到 Starter 中被忽略的部署文件：

npx --yes vercel@54.21.1 env pull .env.production.local --environment=production

切勿提交 .env.production.local，也不要把文件内容粘贴到问题单、构建日志或支持请求中。

3. 预检、迁移与部署

运行唯一的基线入口：

npm run deploy:vercel

该命令从 .env.production.local 加载应用配置，并设置生产运行时标记，避免子命令读取 .env.local。任一步骤失败后都会立即停止：

npm run preflight
npm run db:migrate
npx --yes vercel@54.21.1 --prod --yes

封装脚本只从部署文件导入已知的应用变量。PATH 和 npm 配置等运行时值仍由调用环境控制。

如果环境文件位于仓库之外，请传入绝对路径：

npm run deploy:vercel -- /absolute/path/to/production.env

如果环境文件位于仓库内，文件名必须符合已被忽略的 .env*.local 约定。

4. 验证生产基线

Vercel 报告部署成功后，请在实际部署源地址上验证：

1. 打开首页和本地化登录页。
2. 使用邮箱和密码注册。
3. 收到并打开验证邮件。
4. 登录、退出，然后再次登录。
5. 请求并完成密码重置。
6. 以已登录用户身份打开控制台和账户页面。
7. 确认支付、One Tap 和图片生成功能仍不可用。

构建成功或发生重定向都不足以证明验收通过。请检查真实浏览器流程、Resend 投递状态、应用日志，以及 PostgreSQL 中预期的数据行。

启用支付的部署

当前 npm run deploy:vercel 封装脚本要求 NEXT_PUBLIC_ENABLE_PAYMENTS=false。这是有意为之：该命令代表经过独立验证的核心部署基线，而不是所有可选能力组合。

不要把它描述成支持支付的生产部署命令，也不要通过隐藏已开启的开关绕过检查。请按照支付概览配置并测试支付，然后把启用支付视为一次独立的生产变更。它需要单独进行目标环境预检、测试模式到生产模式的验证、Webhook 投递和数据库回读。当前 Starter 没有把这项变更封装成一条生产部署命令。

更改生产配置

更改基线环境时：

1. 在目标 Vercel 项目中更新变量值。
2. 再次拉取 .env.production.local。
3. 确认本地项目关联正确。
4. 再次运行 npm run deploy:vercel。
5. 重复生产验证。

有关预检、迁移、cron、Webhook 和升级的准确语义，请阅读生产运维。