Cloudflare Pages部署VuePress并接入私有内容源仓库实录
Cloudflare Pages部署VuePress并接入私有内容源仓库实录
一、这次部署的目标
这次不是做一个普通的 VuePress 部署，而是做一条稍微复杂一点的链路：
- 站点仓库：
util6-vuepress-hope - 内容源仓库：
blog-article - 内容源仓库是私有仓库
- Cloudflare Pages 负责构建和发布
- 构建时自动拉取私有内容源，再同步到站点中
换句话说，这次真正要解决的问题不是“VuePress 能不能部署”，而是：
Cloudflare Pages 能不能在构建阶段，安全地读取另一个私有 GitHub 仓库。
二、整体方案
最后落下来的方案是：
- Cloudflare Pages 绑定站点仓库
util6-vuepress-hope - Cloudflare 构建命令执行
npm run docs:build-cf - 构建脚本先拉取私有
blog-article - 从
blog-article/vitepress同步白名单内容 - 再执行 VuePress build
- 内容源仓库 push 后，通过 Deploy Hook 自动触发 Cloudflare 重建
这套方案的优点是：
- 站点仓库和内容源仓库职责分离
- 内容源不用混进站点仓库
- Cloudflare 仍然只部署一个 Pages 项目
三、Cloudflare 表单最终配置
Pages 创建时的关键配置如下：
- 框架预设：
None - 构建命令：
npm run docs:build-cf - 构建输出目录：
src/.vuepress/dist - 根目录：
/
环境变量中，至少需要：
BLOG_ARTICLE_REPO=https://github.com/util6/blog-article.gitBLOG_ARTICLE_REF=<内容源实际分支>GITHUB_REPO_TOKEN=<可读取私有仓库的 GitHub token>GITHUB_REPO_USER=x-access-tokenNODE_VERSION=22.18.0
四、这次部署中真正踩到的坑
1. 不是所有“拉不下来仓库”的报错都一样
这次前后碰到了几种不同错误，它们对应的问题完全不同。
报错一：没有凭据
典型日志：
fatal: could not read Username for 'https://github.com'这说明：
- Cloudflare 构建环境里没有读到
GITHUB_REPO_TOKEN - 或变量加错环境了
- 或变量名拼错了
这时候优先检查：
- 是否真的配置了
GITHUB_REPO_TOKEN - 是否配在生产环境
- 是否重新部署让新变量生效
报错二：403 权限不足
典型日志：
remote: Write access to repository not granted.
fatal: ... 403这不代表真的缺写权限，而是：
- token 已经带上了
- 但 token 没有访问该私有仓库的权限
解决方式是重新配置 GitHub token，而不是继续改脚本。
报错三：找不到分支
典型日志：
fatal: Remote branch main not found这说明：
- 仓库访问已经基本通了
- 只是
BLOG_ARTICLE_REF写错了
比如内容源实际分支是 master，但环境变量写成了 main。
2. Node 版本不能随便用
这次还碰到了 VuePress 对 Node 版本的要求：
22.16.0会有 engine warning- 调整到
22.18.0更稳
所以在 Cloudflare 里明确指定 NODE_VERSION=22.18.0 是值得做的。
3. 构建脚本必须面向云端环境设计
本地能跑，不代表云端能跑。
这次就专门把构建脚本改成了两种模式：
- 本地开发：优先读取本机固定目录
- Cloudflare 构建：优先拉 GitHub 上的内容源仓库
这一步很关键。否则脚本会默认去读本机路径，云端根本不存在那个目录。
五、私有内容源仓库的自动部署方案
最终自动化链路是这样的：
1. Cloudflare Pages 负责构建站点仓库
Pages 项目绑定 util6-vuepress-hope。
2. 构建时拉私有内容源仓库
通过：
BLOG_ARTICLE_REPOBLOG_ARTICLE_REFGITHUB_REPO_TOKEN
在构建阶段执行 git clone。
3. blog-article push 后自动触发站点重建
在 blog-article 仓库里加 GitHub Actions：
- push 到主分支
- 调用 Cloudflare Pages Deploy Hook
这样以后维护动作就变成：
- 改
blog-article - push
- Cloudflare 自动重建站点
六、这次部署后得到的经验
这次最重要的经验不是“会填 Cloudflare 表单”，而是这三点：
1. 部署问题先分层排查
要先判断问题到底属于哪一层：
- 站点仓库代码问题
- Cloudflare 配置问题
- GitHub 凭据问题
- 内容源分支问题
如果不分层，很容易在错误方向上浪费时间。
2. 日志里的报错语义要看细
这次几个典型日志其实已经把问题说得很明白：
could not read Username-> 没拿到凭据403-> 凭据权限不够Remote branch main not found-> 分支名写错
很多时候不是 Cloudflare 难，而是没有把日志里的语义拆开看。
3. 私有仓库联动一定要提前设计权限模型
只要涉及：
- Cloudflare
- GitHub 私有仓库
- 自动触发构建
就必须把这三类权限先设计清楚：
- 谁负责触发部署
- 谁负责读取私有内容
- 哪个 token 放在哪个平台
权限关系没理清，后面一定反复报错。
七、当前这套方案适合什么场景
这套方案特别适合下面这类项目：
- 内容仓库和站点仓库明确分离
- 内容仓库不想公开
- 想继续用 Cloudflare Pages 托管静态站点
- 需要内容 push 后自动触发构建
它不是最简单的 Pages 部署方式，但对于“私有内容源 + 独立站点壳子”这个场景来说，结构是合理的。
八、结语
把 VuePress 部署到 Cloudflare Pages 本身并不复杂。
真正复杂的是：
当站点内容不直接存在站点仓库里，而是来自另一个私有内容源仓库时，如何把构建链和权限链一起打通。
好在这次最终把这件事做通了。
接下来维护就会轻很多：
- 平时只写
blog-article - 站点壳子继续独立演进
- Cloudflare 负责自动构建和发布
这才是这次部署方案真正有价值的地方。