在搭建个人博客时，很多人会将博客的框架代码（如 Hugo/Hexo）、主题文件和文章的 Markdown 文件混在一个 GitHub 仓库里。这虽然简单，但随着文章越来越多，你的写作环境会被各种前端配置文件干扰；而且，如果你想写一些不公开的私密草稿，公开的仓库也无法满足需求。

为了获得最纯粹的写作体验，我采用了**「代码与内容分离」**的架构。今天这篇文章，就来详细聊聊如何基于 Hugo + PaperMod 主题，配合 Cloudflare Pages 部署这样一个现代化的博客。

架构概览：双仓库联动

我的博客由两个 GitHub 仓库组成：

  1. 引擎仓库 (公开)：PaperMod-Blog-Cloudflare
    • 角色：博客的“打印机”与“骨架”。
    • 内容：包含 Hugo 的配置文件、PaperMod 主题、自定义 CSS 等。没有实质性的文章内容。
  2. 内容仓库 (私有)：blog-content
    • 角色：博客的“燃料”与“血肉”。
    • 内容：纯净的 Markdown 文件和图片资源。
    • 优势：设置为 Private（私有），确保草稿和私密笔记的安全。我平时只需要在这个文件夹里用 Obsidian 或 Typora 写作即可。

这两个仓库通过 Hugo Modules（Go Modules 底层）连接。当云端开始构建时，引擎会自动把内容仓库拉取过来，合并渲染成最终的网页。

部署痛点：Cloudflare 如何拉取私有内容？

将公开的引擎仓库绑定到 Cloudflare Pages 非常简单，点几下鼠标即可。但核心难点在于：Cloudflare 在执行 hugo 构建命令时，如何绕过权限阻拦，成功拉取到私有的 blog-content 仓库？

如果不做特殊处理，部署时 100% 会遇到如下报错：

fatal: could not read Username for 'https://github.com': terminal prompts disabled
Error: failed to load modules: failed to get ["github.com/monstercjz/blog-content@upgrade"]

这是因为 Cloudflare 的 CI/CD 环境没有图形界面，无法弹窗让你输入 GitHub 密码。

经过一番折腾，以下是最完美且100%成功的解决方案。

终极部署指南

第一步：获取 GitHub 个人令牌 (Token)

由于内容仓库是私有的，我们需要一个通行证。

  1. 前往 GitHub 的 Settings -> Developer settings -> Personal access tokens (Tokens (classic))。
  2. 点击 Generate new token。
  3. 勾选 repo 权限（Full control of private repositories）。
  4. 生成后，立刻复制并妥善保存这段以 ghp_ 开头的 Token（注意：千万不要把它直接写在代码里或提交到公开仓库！）。

第二步：配置 Cloudflare 环境变量

进入你的 Cloudflare Pages 项目设置，找到 Settings -> Environment variables。添加以下两个变量：

  • 变量 1：告诉 Go 不要通过公共代理拉取私有库
    • Variable name: GOPRIVATE
    • Value: github.com/你的用户名/* （例如：github.com/monstercjz/*）
  • 变量 2：安全地存储你的通行证
    • Variable name: GITHUB_TOKEN
    • Value: ghp_xxxxxxxxxxxxxxxxxxx (你刚才生成的 Token)

第三步：修改魔法构建命令 (Build Command)

进入 Settings -> Builds & deployments，找到 Build command。

传统的构建命令只是 hugo --gc --minify。我们需要在执行 hugo 之前，让 Git 悄悄带上我们的 Token。将构建命令修改为如下这段：

git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/" && hugo --gc --minify

原理解析：

  1. 前半段：利用 git config 将系统环境变量中的 ${GITHUB_TOKEN} 动态注入。告诉 Git：“以后但凡遇到 https://github.com/ 开头的链接，都自动替换为带有 Token 的认证链接”。
  2. &&：当 Git 配置成功后。
  3. 后半段：执行 hugo 构建。此时 Hugo 内部调用的模块下载器就能畅通无阻地拉取你的私有内容仓库了。

总结

完成以上设置后，点击 Retry deployment，看到 Cloudflare 顺畅地拉取了主题、拉取了私有文章，并在几秒钟内将博客发布上线。

现在，可以享受极客般的写作体验了： 打开本地的私有内容文件夹，尽情码字，按下 git push。不用管任何前端代码，几十秒后，全世界就能看到最新文章。这，就是代码与内容分离的魅力所在。