1. 文章库(Posts)绝对安全#

当你执行 git merge upstream/main(同步上游)时:

• 完全不会冲突: Git 知道 src/content/posts 是一个子模块(Submodule),它在主库里只是一行”版本号指引”,上游作者无论怎么修改他自己的示例文章,都绝对碰不到你私有仓库里的文章
• 唯一的变化: 如果上游作者修改了 src/content/posts 这个文件夹的名称(比如改成 src/content/articles),你才需要动一下。但这种改动在成熟的框架里极少发生

2. 配置文件(Config)手动决策#

这是你唯一需要花 1 分钟”动脑子”的地方。当你执行同步命令时:

1
git fetch upstream
2
git merge upstream/main

• 如果没有冲突: Git 会自动合并
• 如果有冲突(通常在 src/config.ts): VS Code 会变红,显示”合并冲突”,你会看到类似这样的代码:

1
<<<<<<< HEAD (你的代码)
2
title: "陌离的博客",
3
=======
4
title: "Firefly Demo",
5
>>>>>>> upstream/main (作者的代码)

操作: 你只需要点击 VS Code 顶部的 “Accept Current Change”(保留我的更改),或者手动删掉作者的那几行,保留你自己的配置即可。

3. 上游增加新功能自动获得#

如果上游作者在 src/config.ts 里新增了一个功能配置(比如新增了评论系统设置):

• Git 会很聪明地把这一行加进来
• 你只需要在合并完后,去填一下这个新配置的值就行了

迁移步骤#

1. 先小范围测试: 首先我先复制了一两个我原来 Fuwari 博客的文章到 Firefly 下面,发现能正常显示,于是便开始大规模迁移。

   注意: 不要一来就将全部内容复制到 Firefly 下面,要是报错了就难搞了。

2. 准备目录结构: 我在 H 盘创建了一个专门存放博客的目录 H:\博客专用,然后:

1
# 克隆自己 Fork 的 Firefly(不是原仓库)
2
git clone https://github.com/moli721/Firefly.git
3

4
# 新建 posts 文件夹,专门存放文章
5
mkdir posts

这样做的好处是:以后只需要去 H:\博客专用\posts 修改文章,然后推送到 GitHub,再让 moli721/Firefly.git 拉取子模块就行。git merge upstream/main(同步上游)时不会冲突。

3. 保留示例文章: 先把 H:\博客专用\Firefly\src\content\posts 复制到我的 H:\博客专用\posts 下面,这样做的好处是保留了原来 Firefly 博客的一些样例和基本格式,以后可以对照。

4. 迁移旧文章: 最后一步就是将 H:\代码\fuwari博客\fuwari-moli721\src\content\posts 下的博客复制到 H:\博客专用\posts 下面直接迁移。

整理示例文章#

迁移后,我让 Claude Code 把原来 Firefly 的示例文章放在 examples 目录下(手动迁移也行)。

修复 Frontmatter 格式#

但是后来也发现 Firefly 的 frontmatter 顺序和 Fuwari 的有些不一样,然后还有些补充。对于强迫症的我不会允许这里不一样,由于文章数量很多,这里不推荐手动修改,直接让 Claude Code 帮你干活,狠狠鞭策 AI!

1
# 让 Claude Code 帮你批量检查和修复
2
# 1. 打开文章目录
3
# 2. 告诉 Claude: "firefly的frontmatter顺序和fuwari的有些不一样,帮我检查所有文章的 Frontmatter,修复格式问题"
4
# 3. Claude 会自动扫描并修复所有文章

到这里,博客文章基本迁移完成了。

1. 删除 Firefly 自带的示例文章#

1
# 确保在 Firefly 根目录下
2
cd H:\博客专用\Firefly
3

4
# 注意: 是 posts(复数)
5
git rm -r src/content/posts

2. 挂载你的私有文章库#

1
# 将你的文章仓库作为子模块添加(替换为你的用户名)
2
git submodule add https://github.com/你的用户名/my-blog-posts.git src/content/posts

3. 安装依赖并启动项目#

重要提示: Firefly 框架的作者强制要求必须使用 pnpm。这是因为 pnpm 速度更快、节省磁盘空间,且能有效避免依赖冲突。如果你执行 npm install,会被内置的校验脚本 only-allow pnpm 拦截。用 npm install 会报错,作者亲身体验!

1
npm install -g pnpm

1
# 安装项目依赖
2
pnpm install

1
# 启动本地预览
2
pnpm dev

4. 提交子模块配置#

1
# 添加所有更改
2
git add .
3

4
# 提交到本地
5
git commit -m "chore: link posts submodule"
6

7
# 推送到你的 GitHub 仓库
8
git push origin main

1. 修改 vercel.json#

解决方案: 删除 vercel.json 中的 installCommand 行。

这里我们需要修改原项目的 vercel.json,将其修改为以下内容,然后提交到项目里:

1
{
2
  "buildCommand": "pnpm build",
3
  "outputDirectory": "dist",
4
  "framework": "astro",
5
  "headers": [
6
    {
7
      "source": "/(.*)",
8
      "headers": [
9
        {
10
          "key": "X-Content-Type-Options",
11
          "value": "nosniff"
12
        },
13
        {
14
          "key": "X-Frame-Options",
15
          "value": "DENY"
16
        },
17
        {
18
          "key": "X-XSS-Protection",
19
          "value": "1; mode=block"
20
        },
21
        {
22
          "key": "Referrer-Policy",
23
          "value": "strict-origin-when-cross-origin"
24
        }
25
      ]
26
    },
27
    {
28
      "source": "/_astro/(.*)",
29
      "headers": [
30
        {
31
          "key": "Cache-Control",
32
          "value": "public, max-age=31536000, immutable"
33
        }
34
      ]
35
    }
36
  ],
37
  "cleanUrls": true
38
}

2. 确保 .gitmodules 使用绝对路径#

然后确保 .gitmodules 使用绝对路径(没改过的不用改,我是因为之前改过)。

原因: 不能用相对路径,在某些环境下好用,但在 Vercel 这种特定的构建容器里会产生歧义。

在本地打开 .gitmodules,将 URL 改回完整的 HTTPS 地址:

1
[submodule "src/content/posts"]
2
  path = src/content/posts
3
  url = https://github.com/moli721/my-blog-posts.git

提交并推送到 GitHub:

1
git add .gitmodules
2
git commit -m "chore: restore absolute URL for submodule"
3
git push origin main

3. 创建 GitHub “经典” Token(Classic Token)#

之前用的 Fine-grained Token(细粒度令牌)虽然安全,但有可能会报错。我试过了,搜索发现它目前对子模块的支持非常差,经常报 403 Write access 错误。我们换成最稳的 Classic Token。

生成 Token#

1. 去 GitHub Settings → Developer settings(在最下面) → Personal access tokens → Tokens (classic)
2. 点击 Generate new token (classic)
3. Note 填 Vercel-Firefly
4. Expiration 选 No expiration(或者你喜欢的时长)
5. 重要: 勾选整个 repo 权限
6. 生成后,复制这个以 ghp_ 开头的字符串(只显示一次,记下来)

4. 在 Vercel 配置环境变量#

然后前往 Vercel 填写相关信息。

步骤 1: 添加环境变量#

在 Vercel 项目 Settings → Environment Variables 里,添加一个变量:

• Key: BLOG_TOKEN
• Value: 填入你刚才复制的 ghp_... 令牌

步骤 2: 配置 Install Command#

去 Settings → Build and Deployment → Install Command。

确保 Override 开启,填入这行代码(避开 403 错误):

1
git config --global url."https://moli721:$BLOG_TOKEN@github.com/".insteadOf "https://github.com/" && git submodule update --init --recursive && pnpm install

注意: 将 moli721 替换为你的 GitHub 用户名。

5. 重新部署(Redeploy)#

回到 Deployments,找最近一次失败的,点 … 选 Redeploy。

1. 日常写文章#

在独立的 posts 目录工作:

1
# 进入文章目录
2
cd H:\博客专用\posts
3

4
# 创建或编辑文章
5
# 注意:必须添加完整的 frontmatter(见下方示例)
6

7
# 提交到文章仓库
8
git add .
9
git commit -m "feat: 新增文章《xxx》"
10
git push origin main

⚠️ 重要提醒: 每篇文章必须包含 frontmatter,否则 Firefly 会报错!

基本 frontmatter 模板:

1
---
2
title: 文章标题
3
published: 2025-12-31
4
description: 文章简介
5
tags: [标签1, 标签2]
6
category: 分类名称
7
draft: false
8
---
9

10
# 文章标题
11

12
文章内容...

可选字段:

1
---
2
title: 文章标题
3
published: 2025-12-31
4
pinned: true              # 添加这行可以置顶文章
5
description: 文章简介
6
image: "./FILES/xxx.png"  # 添加封面图
7
tags: [标签1, 标签2]
8
category: 分类名称
9
draft: false
10
---

2. 本地预览博客#

在 Firefly 目录更新子模块并预览:

1
# 进入 Firefly 目录
2
cd H:\博客专用\Firefly
3

4
# 拉取最新文章
5
git submodule update --remote src/content/posts
6

7
# 本地预览
8
pnpm dev

打开浏览器访问 http://localhost:4321 查看效果。

3. 部署到 Vercel#

确认预览无误后,提交子模块更新:

1
# 在 Firefly 目录下
2
cd H:\博客专用\Firefly
3

4
# 提交子模块引用更新
5
git add src/content/posts
6
git commit -m "chore: update posts to latest version"
7

8
# 推送到 GitHub(Firefly 使用 master 分支)
9
git push origin master

推送后,Vercel 会自动触发部署,大约 1-2 分钟后你的博客就更新了!