为什么想搞这个#

我的博客是 fork 的 CuteLeaf/Firefly，一直有个隐隐的别扭：文章和主题代码挤在同一个仓库里。

平时没事，一合上游就难受。上游挺勤快的，示例文章、文档、demo 项目三天两头动一次；我这边 src/content 里躺着的是自己写的一堆文章和配图。两个东西住在一个目录下，git merge upstream/master 的时候基本就是解冲突体力活。

所以想做个内容分离：文章归文章，主题归主题，各放各的仓库。以后合上游只跟主题代码打交道，src/content 保持上游原样，再也不会打架。

先看别人是怎么做的#

动手之前先去翻了翻别人怎么实现的。

有个博客主题叫 Shirone，它的文档里专门有一章讲内容分离，讲得挺细。看完发现它的做法跟我一开始想的完全不一样——我本来以为要用 git submodule，结果它压根没用。

它的思路是「构建时同步」：

• 主仓库（主题代码）里完全不含内容
• 内容放在另一个仓库，靠一个配置文件声明位置：

1
{
2
  "source": {
3
    "type": "git",
4
    "url": "https://github.com/OWNER/shirone-content.git",
5
    "ref": "main"
6
  },
7
  "mounts": {
8
    "content": "src/content",
9
    "data": "src/data",
10
    "assets": "src/assets",
11
    "public": "public"
12
  }
13
}

• 构建前跑一次同步，把内容仓库浅克隆下来，挂到对应目录
• 私有仓库就用带 token 的 URL 访问，token 放在环境变量里

关键发现：它也没绕开 token。文档原文写得很直白——「需一次性配置访问令牌或部署钩子」。

也就是说，「内容私有 + 云端构建」这两个条件同时存在时，token 是躲不掉的。区别只在于用哪种机制把内容搬进来。

第一版：submodule，白做了#

我一开始还是走了 submodule 这条路，因为看着最”正统”：主仓库里挂个子模块，指向内容仓库，克隆的时候自动拉下来。

做起来也确实不难：

1
cd content
2
git init -b main
3
git add -A && git commit -m "初始化内容仓库"
4
git remote add origin https://github.com/hy4962/firefly-content.git
5
git push -u origin main
6

7
# 回主仓库挂上
8
git rm -r --cached content
9
git submodule add https://github.com/hy4962/firefly-content.git content

本地跑得好好的。推到 GitHub，Vercel 构建——失败。

去看 Vercel 文档，一句话写得明明白白：

Git submodules that are private or requested over SSH will fail during the Build step.

私有 submodule 在 Vercel 上必挂。 给 Vercel 的 GitHub App 授权也没用，社区里一堆人试过了，结论一致：得自己用 token 拉。

也就是说，submodule 这条路的唯一优势（不用管凭证）根本不存在，反而多了一堆毛病：本地克隆要加 --recurse-submodules、主仓库里多了个 .gitmodules、写文章得进子仓库 commit 再回主仓库提交指针。

那还不如照 Shirone 的做法来。

改成构建时同步#

方案换成了：主仓库完全不含内容，构建前用一个脚本把内容仓库拉进 src/site-content/。

脚本很简单，读环境变量、浅克隆、完事：

1
const DEST = path.join(ROOT, "src", "site-content");
2
const URL = (process.env.CONTENT_REPO_URL ?? "").replace(/\s+/g, "");
3

4
// 本地已经有一份就直接跳过，不用每次开发都重新拉
5
if (hasContent && !FORCE) {
6
  log("src/site-content/ 已存在，跳过同步（本地开发模式）。");
7
  process.exit(0);
8
}
9

10
execFileSync("git", ["clone", "--depth=1", "--branch", REF, URL, DEST], {
11
  stdio: "inherit",
12
});

配套的改动是三处：

• src/content.config.ts 里四个 collection 的 glob base 指向新目录
• .gitignore 把内容目录加进去（这样主仓库不再跟踪任何文章）
• vercel.json 的 buildCommand 前置这个脚本

我在 Cloudflare 也有一个部署，那边没有配置文件这一说，构建命令得去面板里手填（设置 → 构建 → 构建命令），填成一样的内容。

注意：这里的路径处理有个细节——脚本用 replace(/\s+/g, "") 把 URL 里所有空白字符清掉了。原因后面踩坑那节讲。

踩坑记录#

1
const files = import.meta.glob<ImageMetadata>(
2
  "../../**/*.{png,jpg,jpeg,webp,avif}",
3
  { import: "default" },
4
);

1
src/
2
├── site-content/     ← 内容在这里（.gitignore 忽略）
3
│   ├── posts/
4
│   ├── spec/
5
│   ├── dynamic/
6
│   └── projects/
7
├── content/          ← 上游的示例文件，原样保留
8
├── components/
9
└── ...

1
warning: url contains a newline in its path component
2
fatal: credential url cannot be parsed

1
remote: Invalid username or token.
2
fatal: Authentication failed

最后一块：内容仓库推送也得能触发部署#

到这一步，文章已经独立了，但它有个新问题：Vercel 和 Cloudflare 只监听主仓库，往内容仓库推文章，它们完全没反应。

解决办法是 Deploy Hook。两个平台都能生成一个 URL，往那个 URL 发个 POST 就会触发一次部署。

在 Vercel：Settings → Git → Deploy Hooks，分支要填对（我填的 HY），不然会部署到别的分支去。

在 Cloudflare：设置 → 构建 → 部署挂链。

然后给内容仓库加一个 workflow，push 的时候去戳这两个地址：

1
on:
2
  push:
3
    branches: [main]
4

5
jobs:
6
  trigger:
7
    runs-on: ubuntu-latest
8
    steps:
9
      - name: 通知构建平台
10
        env:
11
          VERCEL_HOOK: ${{ secrets.VERCEL_DEPLOY_HOOK }}
12
          CF_HOOK: ${{ secrets.CF_DEPLOY_HOOK }}
13
        run: |
14
          if [ -n "${VERCEL_HOOK:-}" ]; then
15
            curl -fsS -X POST "$VERCEL_HOOK" > /dev/null && echo "Vercel 已触发"
16
          fi
17
          if [ -n "${CF_HOOK:-}" ]; then
18
            curl -fsS -X POST "$CF_HOOK" > /dev/null && echo "Cloudflare 已触发"
19
          fi

两个 URL 存进仓库 secret，不写在文件里——curl 出去的地址是能反复触发部署的，明文放在仓库里终究不合适。

顺手把本地流程也改了#

两份副本共存的状态用着别扭，毛病也很快来了：两边都是完整的 git 仓库，我在这边提交、那边还停在旧版本，push 的时候直接被拒（non-fast-forward）。

回头又去翻 Shirone 的文档，发现它的本地开发是这么设计的：

• 用 CONTENT_DIR 指向本地内容仓库，content:sync 一次性把内容同步进代码仓
• 想边写边看，再开一个终端跑 content:watch，增量同步、保存即热重载
• 关键：它的 src/content 是同步脚本物化出来的副本，不是独立的 git 克隆——所以根本没有”两份副本分叉”这回事

我照着改了一版：

• sync-content.mjs 增加 CONTENT_DIR 支持（优先级高于 CONTENT_REPO_URL，本地直接复制、不走网络）
• 新增 watch-content.mjs：监视内容仓库，改动增量同步到 src/site-content/
• 把这两个动作写进本地的 dev.sh / dev.bat（这俩在 .gitignore 里）：先同步 → 后台起监听 → 起 dev server

现在开发一条命令：

1
./dev.sh

在内容仓库里保存 Markdown，watch 立刻同步过去，浏览器热重载。项目里那份 src/site-content/ 彻底变成生成物——删了也无所谓，下次同步就回来了，也不再有两边版本对不上的问题。

现在的样子#

写文章的流程：

1
cd D:\Users\XOS\Documents\GitHub\firefly-content
2
# 写文章
3
git add . && git commit -m "新文章：xxx" && git push

推完不用管，Vercel 和 Cloudflare 各自会重新拉一遍内容、构建、上线。

本地想预览效果：

1
cd D:\Users\XOS\Documents\GitHub\Firefly
2
./dev.sh

主仓库那边现在是什么状态：git ls-files src/site-content 返回 0，一个文章文件都不跟踪，只留主题代码和配置。以后 git merge upstream/master 只跟主题较劲，src/content 是上游的原样，不会再打架。

几个结论#

如果只是给主题仓库做内容分离，有几点值得先知道：

1. 私有 submodule 在 Vercel 上不能用，这是官方明确写的限制。别像我一样先做完再发现。

2. token 躲不开。内容要私有、又要云端构建，凭证是必须的。区别只是用 submodule 还是构建时同步。

3. 内容目录必须落在 src/ 里面。主题的图片解析是写死扫 src/ 的（import.meta.glob("../../**")），放外面封面和配图会全部消失。

4. 粘贴环境变量后检查一眼。输入框角落的警告图标不是装饰，一个换行符就能让你排查半小时。

5. 早年提交过的内容还留在历史里。这套改动只管往后——主仓库从今以后不跟踪任何文章，但之前提交过的那些依然在历史记录中。要不要一并清理是另一个决策：重写历史意味着所有 commit hash 变化、必须 force push，跟上游的关联也会变复杂。我的情况没必要，就留着了。

6. 本地开发别用”两份克隆”。一开始我在项目里放了个独立克隆当预览源，结果两边各写各的、push 时撞车。改成 CONTENT_DIR 指向外部目录 + 一个 watch 脚本之后，项目内那份变成纯粹的生成物，问题就没了。