Pages CMS 部署到 Vercel | 向野而深的博客

将 Pages CMS 部署到 Vercel 的过程本质上是构建一个 Next.js 全栈应用。拆解成以下四个核心阶段。

## 第一阶段：准备外部基础设施（必须先完成）

在点击 Vercel 部署按钮前，你需要准备好两个外部服务的凭证：

数据库 (PostgreSQL):
- 推荐使用 Supabase（文档推荐）。
- 注册并创建一个新项目。
- 在项目设置中找到 连接字符串 (Connection String)，选择 Transaction pooler 模式的 URL。它看起来像：postgresql://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres。
邮件服务 (Resend):
- 注册 Resend。
- 添加并验证你的域名（用于发送登录验证码）。
- 生成一个 API Key。

这是最关键的一步，用于授权 Pages CMS 操作你的仓库。

访问你的 GitHub 设置中的 GitHub Apps。
点击 New GitHub App：
- Callback URL: 先填一个占位符（如 https://localhost:3000/api/auth/github），等 Vercel 部署完有了正式域名后再回来改。
- Webhook: 勾选 Active。Webhook URL 同样先填占位符。
- Webhook Secret: 自己生成一个随机字符串（记下来，后面要填到 Vercel）。
权限设置 (Permissions):
- Repository -> Administration: Read & Write
- Repository -> Contents: Read & Write
- Repository -> Metadata: Read-only
订阅事件 (Subscribe to events): 勾选 Installation target, Repository, Push, Delete。
生成凭证: 保存后，记录下 App ID、Client ID，并生成一个新的 Client Secret 和 Private Key（下载 .pem 文件，用文本编辑器打开获取内容）。

你可以直接点击文档中的 Deploy 按钮，或者手动在 Vercel 中导入你 Fork 的仓库。

在 Vercel 的部署界面，你需要填入以下变量：


变量名	来源 / 获取方式
`DATABASE_URL`	Supabase 的连接字符串。
`CRYPTO_KEY`	运行 `openssl rand -base64 32` 生成的随机字符串。
`GITHUB_APP_ID`	GitHub App 详情页的 ID。
`GITHUB_APP_NAME`	GitHub App 的 URL 里的那个名字（Slug）。
`GITHUB_APP_PRIVATE_KEY`	`.pem` 文件的完整内容（包含 BEGIN/END 标志）。
`GITHUB_APP_CLIENT_ID`	GitHub App 详情页的 Client ID。
`GITHUB_APP_CLIENT_SECRET`	你刚才生成的 Client Secret。
`GITHUB_APP_WEBHOOK_SECRET`	你在 GitHub App 设置里填的 Webhook Secret。
`RESEND_API_KEY`	Resend 提供的 API Key。
`RESEND_FROM_EMAIL`	你在 Resend 验证过的发件邮箱（如 `admin@yourdomain.com`）。

部署完成后，Vercel 会给你一个公网域名（如 https://pages-cms-six.vercel.app）。

数据库初始化： 部署完成后，如果页面报错，可能需要运行数据库迁移。由于 Vercel 是 Serverless 环境，建议在本地环境执行一次 npm run db:migrate（确保本地 .env 连接的是同一个 Supabase 数据库）。
私钥格式： 在 Vercel 填入 GITHUB_APP_PRIVATE_KEY 时，如果遇到换行符问题，确保粘贴的是原始格式。
缓存问题： 如果你修改了 GitHub 里的文件，Pages CMS 没反应，检查 Webhook 是否在 GitHub App 后台显示发送成功（Redeliver 记录）。