保姆级教程：使用 Vercel 免费部署 Pages CMS
引言
Pages CMS 是一个现代化、开源且可自托管的内容管理系统，特别适合与静态网站生成器（如 Hugo、Next.js、Astro 等）配合使用。它允许你和非技术人员通过一个简洁的界面直接编辑 Git 仓库中的 Markdown 文件，无需接触代码。
本教程将手把手教你如何将 Pages CMS 免费部署到 Vercel 上，并连接到你的内容仓库。
准备工作
在开始之前，请确保你拥有以下条件：
- 一个 GitHub 账号 (用于 Fork 和认证)。
- 一个拥有静态网站内容的 Git 仓库 (这个仓库就是你想要用 CMS 管理内容的仓库)。
- 一个Vercel账号（用于部署pages CMS）。
第一步：Fork Pages CMS 主仓库
- 访问 Pages CMS 官方仓库：https://github.com/hunvreus/pagescms
- 点击右上角的 Fork 按钮，将这个仓库复制一份到你的 GitHub 账户下。
为什么要 Fork？ 这样你就可以拥有自己的 Pages CMS 实例并进行个性化配置。
第二步：创建GitHub APP
2.1、注册新的Github APP
- 点击GitHub右上角的账户头像找到Settings
- 下拉页面在左下角找到Developer settings
- 然后在左上角找到Github Apps
- 然后点击右上角的New OAuth App。
2.2、填写基本设置
在注册页面，按以下要求填写字段：
| 字段 | 填写内容 |
|---|---|
| GitHub App name | 任意唯一名称（如 my-pagescms-app） |
| Homepage URL | 你的 PageCMS 管理页面地址（例如 https://your-site.com） |
| Redirect URI | https://pagesCMS管理页面地址/api/auth/callback/github |
| Webhook URL | https://pagesCMS管理页面地址/api/webhook/github |
| Webhook Secret | 自己随机生成的64秘钥（保存好，后面要用） |
2.3、配置权限（最关键部分）
根据 PageCMS 文档要求，必须授予以下 最小必要权限：
Repository permissions（仓库权限列表）
| 权限区域 | 权限级别 |
|---|---|
| Contents | Read & Write（读取和写入仓库内容） |
| Metadata | Read-only（默认已有） |
| Pull requests | Read & Write（管理 Pull Request） |
| Administration | Read-only（读取仓库设置） |
| Commit statuses | Read & Write（更新提交状态） |
| Deployments | Read & Write（管理部署） |
| Environments | Read-only（读取环境配置） |
注意：这些权限是 PageCMS 正常运行的最低要求。不要授予不必要的额外权限。
Organization permissions（组织权限）
- 如果仓库属于组织，建议保持默认（通常不需要额外权限）
Subscribe to events（订阅事件）
- PageCMS 不需要监听 GitHub 事件，保持所有选项不勾选。
2.4、其他设置
| 设置项 | 填写内容 |
|---|---|
| Where can this GitHub App be installed? | 选择 Only on this account（仅限你的账户）或 Any account（如果打算分享给他人） |
| Post Installation | 填写 PageCMS 管理页面地址（例如 https://your-site.com） |
| Request user authorization (OAuth) during installation | 取消勾选 |
2.5、生成密钥并保存 App ID
- 点击 Create GitHub App 创建应用
- 在 App 管理页面中找到：
- App ID：复制并保存（后续配置需要）
- Client ID：复制并保存（后续配置需要）
- Client secrets：复制并保存（后续配置需要）
- Private keys 区域：点击 Generate a private key
- 下载
.pem文件（私钥文件，务必妥善保管）
2.6、 安装 App 到指定仓库
- 在左侧导航栏点击 Install App
- 选择目标账户或组织
- 选择安装范围：
- 选择 Only selected repositories
- 勾选你想要 PageCMS 访问的 GitHub Pages 仓库（不要安装在第一步Fork的仓库）
- 点击 Install 完成安装
- 安装完成后，记录下 Installation ID（可选，但某些高级配置可能需要）
第三步、创建Neon数据库
3.1、注册/登录 Neon
- 打开 Neon Console
- 点击 Sign In，支持以下方式登录：
- GitHub 账号
- Google 账号
- 邮箱注册
- 新用户会看到欢迎页面，点击 Create a project 开始
3.2、创建项目（Project）
- 点击 New Project 按钮
- 填写项目信息：
| 字段 | 说明 |
|---|---|
| Name | 项目名称（如 my-app-db） |
| Region | 选择离你最近的区域（如 AWS US East (N. Virginia)） |
| PostgreSQL version | 选择版本（建议选最新的稳定版，如 16） |
- 点击 Create Project 完成创建
- 系统会自动生成：
- 数据库名称（默认与项目名相同）
- 用户名（自动生成）
- 密码（自动生成，只显示一次，请立即保存）
- 连接字符串（Connection String）（复制并保存) ）
第四步：在 Vercel 上进行初始部署
4.1、创建新的项目
- 登录你的 Vercel 账户。
- 点击 Add New 按钮，选择 Project。
- 在 “Import Git Repository” 部分，找到并导入你刚刚 Fork 的那个 Pages CMS 仓库。
- 在配置页面，Vercel 会自动识别这是一个 Next.js 项目（因为 Pages CMS 基于 Next.js 构建）。你不需要修改任何构建命令或输出目录。
4.2、填写环境变量
这是最关键的一步。你需要告诉 Pages CMS 你的内容仓库是哪里的，以及如何与之通信。在 Vercel 项目的配置页面，找到 Environment Variables 部分，添加以下变量：
| 字段 | 值 |
|---|---|
| BASE_URL | 你的 PageCMS 管理页面地址（例如 https://your-site.com） |
| GITHUB_APP_ID | 前面复制保存的APP ID |
| GITHUB_APP_CLIENT_ID | 前面复制保存的Client ID |
| GITHUB_APP_CLIENT_SECRET | 前面复制保存的Client secrets |
| GITHUB_PRIVATE_KEY | 前面下载的 .pem 文件（复制值的时候回车换行要换成\n) |
| GITHUB_APP_WEBHOOK_SECRET | 前面生成的Webhook Secret |
| BETTER_AUTH_SECRET | 使用openssh生成的base64密钥 |
| CRYPTO_KEY | 使用openssh生成的base64密钥（与BETTER_AUTH_SECRET不能相同） |
| DATABASE_URL | 前面复制保存的Connection String |
4.3、部署并验证
- 确认所有环境变量填写无误后，点击 Deploy 按钮。
- 等待部署完成（通常只需要 1-2 分钟）。Vercel 会自动构建并为你生成一个
*.vercel.app的域名。 - 部署成功后，访问你的
PAGES_CMS_URL。 - 你应该能看到 Pages CMS 的登录界面。如果你配置了 OAuth，点击 “Log in with GitHub” 即可；如果使用了 Token，你将自动进入管理面板。
第五步：配置内容仓库 （可选）
为了获得最佳体验，你可以在你的内容仓库根目录下创建一个 pages-cms.yml 配置文件。这可以定义集合、字段和媒体目录。
例如：
|
|
常见问题 （FAQ）
- 部署失败了怎么办？
- 检查 Vercel 的 Build Log，确认环境变量是否传递成功。
- 确保 Fork 的是最新的主分支。
- 点击 “Log in with GitHub”返回GitHub404怎么办？
- 检查GitHub APP权限是否都在设置正确，可参考pages CMS官方文档
总结
恭喜！你现在已经拥有了一个属于自己的、免费的、云端 CMS。你可以随时随地通过浏览器管理你的博客或文档内容，编辑完成后直接提交到 Git，结合你的 CI/CD 流程，整个发布过程无缝且高效。
这个方案最大的好处是：免费、开源、数据自主可控。快去试试吧！