GitHub Pages + Vercel 双仓部署指南

前言#

如果说用 Vercel 部署个人博客是一种“随手即得”的快乐，那么使用 GitHub Pages 部署博客，更像是一种“更接近底层逻辑”的练习。它没有那么多平台帮你兜底的自动推断，也正因为如此，你会更清楚地理解：构建产物是什么、发布仓库是什么、为什么要区分源码和站点、为什么有些东西该提交、有些东西不该提交。

这篇文章记录的，就是我把博客做成“源码私有仓库 + 公开 Pages 发布仓库”的全过程。与上一篇一样这既是一个给我自己的记录，又是一个写给大家的操作教程。但这一切都有一些前提条件：

• 已经有一个本地能跑起来的博客项目；
• 希望源码仓库保持私有，但站点必须公开访问；
• 想把 GitHub Pages 和 Actions 这套流程真正打通；
• 不想每次手动复制 dist/，而是希望 push 代码后自动发布。

Part 1：先理解这套方案到底在做什么#

如果你是第一次接触 GitHub Pages，很容易把“源码仓库”和“发布仓库”混在一起。实际上，在双仓部署方案里，它们扮演的是完全不同的角色。

为什么要拆成两个仓库？#

简单来说，我们希望同时满足两个目标：

• 源码尽量私有：因为博客源码里会包含主题配置、工作流、一些尚未发布的内容，甚至有时会带上实验中的功能。
• 站点必须公开：因为 GitHub Pages 最终是给别人访问的。

如果把所有东西都堆在一个仓库里，当然也不是不行，但你会在“源码是否公开”“发布产物是否提交”“Pages 从哪一个目录读取文件”这些问题上不断纠结。双仓方案的好处就是职责清晰：

• [用户名]/[仓库1]：私有源码仓库
• [用户名]/[用户名].github.io：公开发布仓库

前者负责写代码、写文章、执行构建；后者只负责承载已经构建好的静态网页。

这套流程的本质是什么？#

本质上，我们做的事情只有三步：

1. 在私有的源码仓库里执行静态构建，得到 dist/
2. 通过 GitHub Actions 把 dist/ 推送到公开仓库根目录
3. 让 GitHub Pages 从公开仓库的 main / (root) 发布网站

Part 2：开始之前，我们应该已经有什么#

在往下操作之前，最好先确认下面这些前提已经满足。

准备好仓库#

其中第二个仓库必须是 public。这点很重要，因为用户站点型的 GitHub Pages 最终要稳定公开访问，而公开仓库在这方面是最省心的。

准备好本地项目#

你的博客项目至少要满足：

• 本地 pnpm build 能成功；
• 项目已经支持 GitHub Pages 模式构建；
• 构建产物输出到 dist/；
• 你知道源码仓库和发布仓库分别是谁。

如果这些还没完成，那建议先根据我的博客上手指南 ↗将本地构建打通，然后再继续下面的自动发布。因为 Actions 本质上也只是把本地的那套流程搬到了云端执行一遍。

Part 3：生成 Deploy Key#

这一步十分的关键，也是整个双仓发布里最容易让人卡住的点，但原理其实并不复杂。

我们需要一把“钥匙”，让私有源码仓库里的 CI 可以合法地向公开发布仓库 push 内容。这把钥匙就是 SSH Deploy Key。听起来很复杂，但是不要怕，让我step by step的教你。

在本地生成密钥对#

在你本地任意目录执行：

ssh-keygen -t ed25519 -C "pages-deploy" -f pages_deploy_key -N ""

执行完成后会生成两个文件：

把公钥和私钥分别放到正确的位置#

这一步最容易搞错的，不是操作本身，而是“到底哪个钥匙要放在哪个仓库里”。

1. 公钥放到公开发布仓库（允许写入）

2. 私钥放到私有源码仓库的 Actions Secret

Part 4：启用 GitHub Pages#

到了这一步，发布仓库其实已经具备“被推送内容”的能力了。接下来要做的是告诉 GitHub Pages：你应该从哪里读取这些静态文件。

进入仓库：[用户名]/[用户名].github.io

打开：Settings to Pages

然后设置：

保存之后，正常情况下 Pages 的地址会是：

https://[用户名].github.io/

Part 5：源码仓库里的自动发布#

你当前的源码仓库里，实际上已经具备这套自动发布流程了。也就是说 workflow 不是从零开始设计的，而是已经被改造成下面这条链路：

自动发布链路#

1. 你在私有源码仓库提交并 push
2. GitHub Actions 被触发
3. Actions 以 DEPLOYMENT_PLATFORM=github 进行静态构建
4. 构建产物输出到 dist/
5. workflow 使用 Deploy Key 把 dist/ 推送到 [用户名]/[用户名].github.io 的 main 分支根目录
6. GitHub Pages 从根目录读取静态文件并刷新站点

至此，就实现了 GitHub Pages + Vercel 双平台的个人博客部署，你可以根据他们的网站分别尝试进行打开，就好好欣赏你的劳动成果吧，我相信它会让你感到有趣并有成就感的！当然，接下来对博客的内容的构建与界面的搭建就要靠你自己辛勤耕耘了，坚持把它打造成有你自己风格的一块天地吧！

小结#

当你真的把这套流程走通之后，会发现 GitHub Pages 并没有想象中那样复杂。它真正复杂的地方，不在于某一条命令，而在于第一次建立完整心智模型的时候：谁负责构建、谁负责发布、谁负责公开访问、谁握着写权限。

一旦这个模型搭起来，后面的事情反而会变得非常顺手，你只需要像平常一样写文章、改配置、提交代码，剩下的构建与发布都交给 Actions 自动完成。

更重要的是，这套双仓方案并不只适用于博客。任何走静态构建路线的网站——产品主页、作品集、文档站、个人简历——其实都可以复用这一套思路。

把源码留给自己，把成果交给世界。这就是这套发布方式最让我喜欢的地方。