0 定个调子#

目标三条，按优先级：

1. 换掉 Hexo → Astro
2. GitHub Pages → Cloudflare Workers
3. 旧 URL 一个都不能死

第三条是硬约束。十年攒下来的外链和搜索引擎收录都指着 /年/月/日/标题/ 这个格式，改了就等于把自己的历史删了。后面会看到，整场搬家里最费劲的就是这一条。

CAUTION

选 Workers 不选 Pages。CF 正在把 Pages 吸收进 Workers，新功能只进 Workers，2026 年开新项目官方建议就是 Workers + Static Assets。别再 wrangler pages deploy 了。

选 Astro 的理由也很实在：@astrojs/cloudflare 能让预渲染的静态页和 /api/* 动态接口共存在同一个 Worker、同一次部署里。以后想加评论、加阅读计数，不用拆项目。

主题挑了 Fuwari——骨架跟我原来的 icarus 一样（左边 profile、中间正文、右边目录），迁移的心理落差最小。

1 摸底：先别写代码#

动手前先把老站摸清楚。这一步一行代码都别写，纯调查，结论如下：

RSS 那条挺打脸的——我一直以为我有 RSS。翻遍 public/ 连个 atom.xml 都没有。没有历史包袱反而轻松，新建一个就行。

然后是这次搬家的头号坑：

CAUTION

83 篇文章全部缺少 front-matter 的前导 ---。

Hexo 允许你省略开头那行分隔符（只有结尾有 ---），但 gray-matter / Astro 要求两边都有。不补这一行，整个 front-matter 会被当成正文渲染出来。

迁移脚本干的第一件事就是补它。

还有一堆 Hexo 专有的标签插件要处理：

最后两个畸形文件名，看着手痒也不能改：

• rbp3-upgrade-raspbian.md.md —— URL 真的就是 /2018/02/15/rbp3-upgrade-raspbian.md/
• writing-os-in-rust-on-rpi_.md —— 尾巴上真的挂着一个下划线

改了就是断链。忍住。

2 迁移脚本：能重跑、能空跑、能吐日志#

83 篇不可能手改。写个脚本，三个要求：幂等（重跑结果一样）、dry-run（先看不写）、转换日志（改了什么一目了然）。

原始 markdown 是唯一真相，一个字节都不动，转换结果全写到新目录。

1
node scripts/migrate.mjs --dry-run          # 空跑，只看日志
2
node scripts/migrate.mjs --only transformer # 单篇调试
3
node scripts/migrate.mjs --force            # 真写（会先清空输出目录，所以要显式 --force）

核心是个「遮罩」的把戏。代码块里的东西一个字都不能碰——你总不希望我把你文章里演示 {% raw %} 用法的那段代码给”转换”了。所以先把代码块整段替换成占位符，处理完正文，再塞回去：

1
// 先把围栏代码块、行内代码换成占位符，正文处理完再塞回来。
2
// ⚠️ 两层遮罩必须用不同的哨兵，否则内层还原时会把外层的占位符一起吃掉。
3
// 哨兵用不可打印的控制字符，保证它绝不可能出现在正文里。
4
const MARK_FENCE  = "\u0000";
5
const MARK_INLINE = "\u0001";

这个坑我是真踩了：一开始两层用同一个标记，内层一还原，外层占位符全被啃了。更蠢的是我最早用 " N " 这种人类可读的占位符——结果它把正文里的数字也吃了。

front-matter 的字段映射：

1
# Hexo                    # Fuwari
2
date:       → published:
3
categories: → category:   # 数组变单数，取第一个
4
title/tags/description    # 同名，不动
5
                          # 外加一行 slug: 2024/01/06/文件名

那行 slug: 就是保住旧 URL 的关键，下一节说。

跑完的统计：

1
admonition=58  assetImg=15  img=1  link=4  iframe=1
2
mathFix=4      fenceFix=1   langFix=16

3 校验：写校验器比写脚本还重要#

脚本跑完了，怎么知道它没偷偷吃掉我的文章？

写了四道校验：

然后就抓到了这次最阴的一个 bug。

1
Pin<&mut Self>

4 旧 URL：一个都不许死#

老站的 URL 长这样：

1
https://zlotus.github.io/2024/01/06/transformer-from-scratch-1/

Astro 默认会给你 /posts/xxx/。差一个字都是断链。

解法是让 front-matter 里的 slug 直接装下完整路径，再建一个四段的路由文件把它拆回来：

1
src/pages/[year]/[month]/[day]/[...slug].astro

1
const [year, month, day, ...rest] = entry.slug.split("/");
2
if (!year || !month || !day || rest.length === 0) {
3
    // 宁可构建失败，也不要静默生成一个错的 URL
4
    throw new Error(`${entry.id} 的 slug 不是 YYYY/MM/DD/name 格式`);
5
}

这里有个陷阱：URL 是改 URL 的地方越少越好。我把全站所有生成文章链接的地方（列表、上一篇/下一篇、RSS、TOC 高亮判断）全都掐到同一个函数上：

1
export function getPostUrlBySlug(slug: string): string {
2
    return url(`/${slug}/`);
3
}

漏了两个：RSS 自己拼了 /posts/${slug}/，TOC 用 startsWith("/posts/") 判断当前是不是文章页——后者会让目录永远不显示。

NOTE

一个值（这里是 URL 格式）应该只有一个说了算的地方。散落在五个文件里各拼各的，就一定会漏。

至于列表页（/page/2/、/tags/xxx/、/categories/xxx/）这些，我不打算在 Astro 里复刻 Hexo 的分页结构，直接上 301：

1
/page/:num/              /:num/                   301
2
/tags/:tag/              /archive/?tag=:tag       301
3
/categories/:cat/        /archive/?category=:cat  301
4
/archives/               /archive/                301

最后拿老站的 URL 全集跑一遍新站——注意必须发真实 HTTP 请求，重定向是没法靠”文件存不存在”验证的：

1
207 个 URL，207 个可达（其中 123 个走 301），0 个 404

5 部署：GitHub Actions → Workers#

老站是 hexo deploy 一把 force-push。新站换成 CI：push 到 main，GitHub 的机器上构建，wrangler deploy 推到 Cloudflare。

1
on:
2
  push:
3
    branches: [main]
4
    paths-ignore:
5
      # 改这些不影响构建产物，别浪费一次部署
6
      # ⚠️ 不能写 '**.md'——src/content/posts/*.md 是文章，改了必须重新部署！
7
      - "CLAUDE.md"
8
      - "legacy/**"
9

10
jobs:
11
  deploy:
12
    runs-on: ubuntu-latest
13
    steps:
14
      - uses: actions/checkout@v4
15
      - uses: pnpm/action-setup@v4       # 不写死版本，让它读 package.json
16
      - uses: actions/setup-node@v4
17
        with:
18
          node-version: 22
19
          cache: pnpm
20
      - run: pnpm install --frozen-lockfile
21
      - run: node scripts/check-math.mjs src/content/posts  # 坏公式别上线
22
      - run: pnpm build
23
      - uses: cloudflare/wrangler-action@v3
24
        with:
25
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
26
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
27
          command: deploy

顺便，GitHub Pages 那个”Page not found”也自愈了：Pages 是 force-push 之后异步重建，那一两分钟里访问就是 404；Workers 是原子切换，新版本上线之前老版本一直在服务。

1
gh secret set CLOUDFLARE_API_TOKEN   # 然后在提示符里粘贴 token

1
CFUT_AJQNNMQCIBA9PFAFY01QYD5ZAW7SMUYDVJCJYN1I0365B2F8   ← 这是我的 token……
2
D6B51B94502C5FAA231B1544A3690BA8                        ← 这是我的 account id……

6 白嫖能白嫖到什么程度#

这是整件事的重点——全部落在免费额度内。

几条自己给自己划的红线：

• 别拿 KV 做阅读计数器——一天 1000 次写，一天就打满。要计数用 D1。
• 别做运行时 OG 图渲染——10ms CPU，satori 之类必超。OG 图构建期生成。
• 别碰 Containers——没有免费额度，要 $5/月。

搜索用 Pagefind，这东西的思路很对我胃口：它不是搜索服务，是个后处理器。astro build 生成完 HTML，它去爬构建产物、切词、建索引，产出一堆静态分片；浏览器搜索时按需下载命中的分片。

全程零后端。 Cloudflare 那边只是当图床发文件——而静态资源请求不计配额。等于白嫖到底。

7 以后怎么写文章#

这一节是写给未来的我看的。三个月后我肯定忘光。

1
cd ~/zlog
2
pnpm new-post my-new-post     # 文件名用英文！

1
pnpm dev            # localhost:4321，热更新，日常写字用这个

1
pnpm build          # 必须先 build——Pagefind 索引是构建期生成的
2
npx wrangler dev    # localhost:8787

1
git add -A
2
git commit -m "新文章：十年老blog搬家"
3
git push                      # ← 就这一下，没了

1
gh run watch          # 盯着这次构建
2
gh run list --limit 3 # 最近三次的结果

后记#

搬完了。83 篇全在，旧 URL 一个没死，公式代码图片都好，还顺手修了老站两个 bug。

回头看，真正花时间的不是”用 Astro 重建一个博客”——那部分快得离谱。花时间的是：

• 搞清楚老站到底是什么样（Phase 0 那张表）
• 证明新站和老站一模一样（四道校验）
• 保证十年的链接不断（207 个 URL 逐个发请求）

以及一个反复出现的教训：

NOTE

代码写完不算完，验证过才算完。

这次所有的坑——六个反引号、TOC 不显示、RSS 拼错路径、</div></p>、单数字日期——没有一个是我”读代码”读出来的，全是校验器跑出来的。

而唯一一个校验器自己出的错（Rust 泛型误报），恰恰是因为校验器写复杂了。

现在挂在 Cloudflare 上，橙云一开，国内访问也没问题。

下一步大概是评论和阅读计数——不过那得等我先用几天，看看到底需不需要。YAGNI。