三个需求，一个时间点#

这次迁移有三个动机：一个推力，两个拉力。

推力：我不想再给 minima 打补丁了。下一节展开这笔账，这里只说结论：两年下来，博客的定制全部以 include 的形式贴在正文里，每一层补丁都让下一层更贵，“给博客加点东西”的预期成本已经超过了”重写”。

拉力一：我需要一个 landing page。博客索引页干不了这件事，它只会按时间倒序列文章，但是我要的是一个能自由排布的入口：最近写什么、做过什么、现在什么状态。在 minima 里实现它，需要先 fork 主题的 home layout，再往上贴五层补丁。

拉力二是多语言。内容网站默认是静态的，我的博客却是双语的，而且”双语”在我这里有一个很具体的含义：找 coop 的时候，recruiter 顺着简历点进来，看到的不能是一屏中文 write-up。这个需求拆开是两半。一半是内容要有中英两个版本，这半 Jekyll 有插件能做，但 GitHub Pages 托管的 Jekyll 只跑白名单插件，多语言插件不在名单上，想用就得本地构建再推产物，等于把 CI 的活搬回自己电脑，回到工具链那笔旧账。另一半是按访客的语言筛选和切换内容，这是个运行时的决定，纯静态托管天生没长这个器官，要补只能再往正文里贴一层 <script>，补丁债务的同一个病。落地放在第 3 节说。

还有一笔不算动机、但一直在计息的成本：Ruby 不在我的工具链里。每次回到这个项目，开场都是 bundle install，然后是某个 gem 的版本问题，某个奇怪的 PATH 问题，而我 debug 用的是一门我不写的语言和一个我不熟的包管理器。Jekyll 本身不慢，慢的是我每次进场的门票。

方向其实早就定了。写 htmx 那篇的时候，我用一整节讲岛屿架构，说 Astro 把它做成了一等公民：默认零 JS，哪个组件需要运行时哪个才有。一个”内容为主、交互按需”的博客，一个”高度自由、自行裁切”的 landing，一个”静态为底、动态按块”的多语言机制，三个需求指向同一个框架。只有其中任何一个，答案都不一样：只为了 landing，开个新仓库随便搭；只为了逃离 minima，换个主题继续 Jekyll 也能混；只为了多语言，硬着头皮本地构建再推产物也行。三个撞在一起，“一个 monorepo、一套 Astro、两种产物”才成了唯一合理的形状。

我在 minima 里 hack 了什么#

1
{% include override-styles.html %}
2
{% include load-barlow-font.html %}

1
{% include override-styles.html %}
2
{% include load-barlow-font.html %}
3
{% include math-support.html %}
4
{% include mermaid-support.html %}

1
*:not(code, .katex *) { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; }
2
code, span:is(.highlight *) { /* … */ background-color: #f0f0f0 !important; }

1
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.18.6/dist/katex.min.js"
2
    integrity="sha384-7jGyG5zFwmEamqNWdCbpsPn+GTWEis3lnV7X/jXHyhFpJG7ExABLyMapabg8F4+p"
3
    crossorigin="anonymous"></script>
4
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.18.6/dist/contrib/auto-render.min.js" ...
5
    onload="renderMathInElement(document.body, { delimiters: [/* … */], throwOnError: false });"></script>

1
mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
2
mermaid.run({ querySelector: 'code.language-mermaid' });

1
{% include center-figure.html src="/assets/2025-08-07-a-brief-introduction-on-impedance/Low_pass_filter.png"
2
    alt="LC Circuit" maxw="400px" maxh="400px" %}

为什么落在 Astro 和 Fuwari#

迁移选型的判据有三个，按重要程度排。

第一，一个工具要能同时回答三个需求。博客要内容管线：content collections 把 markdown 收编成有 schema 的数据，remark/rehype 插件链管渲染，RSS、sitemap、阅读时长都有现成的形状。landing 要自由前端：路由、组件、样式全听我的。多语言要第三样：页面静态生成，动态收缩成几个孤立的组件。Astro 恰好三样都给。

第二，JS 的粒度要落到组件级。博客绝大部分内容是静态的，但总有几个组件要活，多语言的两个切换器就是活的那几个；landing 干脆一行客户端 JS 都没有，需求就到这。Astro 的默认值正好是”没有 JS，除非你要”。这个判断的完整版本在 htmx 那篇的第 7 节，这里不重复。

第三，工具链得是我自己的。npm、TypeScript、Vite，这是我日常 debug 的栈，构建出错时我读得懂每一行报错。这条听起来理所当然，但在 Jekyll 那边，它是两年里反复出血的伤口。

被否掉的简单说。Hugo 是同一个病的另一个患者：主题模型、模板在别处、定制靠覆盖，多语言一样要靠插件拼装，只是模板语言从 Liquid 换成 Go template。Next 是另一个方向的重：为一个以静态为主的站点引入运行时和部署假设，换来的能力我一样都用不上。

但是这个博客不是从零写的，起点是 Fuwari，一个 Astro 博客主题，或者更准确地说，材料。这里要说清楚，“fork 一个主题”和第 2 节骂了两千字的”主题模型”有什么区别。

区别在代码住在哪。minima 的模板躺在 gem 里，我能做的只有覆盖和注入；Fuwari 的整个 src/ 躺在我的仓库里，主题机制本身，处理 mermaid 的 remark 插件、算摘要和阅读时间的插件、渲染卡片的 rehype 组件，全是 src/plugins/ 下有名字、能 diff、能改的文件。fork 它的那天，主题的维护者就变成了我。这正是第 2 节说的”分叉的所有权”，只不过这次我拿走了所有权。

接管之后动过的地方，大致是一份插件清单：mermaid 的围栏代码块在构建期转成 <pre class="mermaid-src">，交给前端渲染；remark-excerpt 和 remark-reading-time 生成列表页的摘要和时长；GitHub 卡片、链接卡片、admonition 走 rehype-components；代码块换成 expressive-code，调了字体和配色。这些没有一样是”配置主题”，全是在写自己的构建管线。

1
<div id="toc-card" class="hidden lg:block sticky top-4 mt-4">
2
    <WidgetLayout id="toc-widget" ...>
3
        <div id="toc-inner-wrapper" class="max-h-[calc(100vh-12rem)] overflow-y-auto ...">
4
            <TOC headings={headings} />

1
const mermaidRuntime = (window as unknown as { __mermaidRuntime?: MermaidRuntime })
2
  .__mermaidRuntime ??= { mounted: false, queue: Promise.resolve() };
3

4
function scheduleMermaidRender(): void {
5
  mermaidRuntime.queue = mermaidRuntime.queue.then(renderMermaid);
6
}

一个仓库，两个 project，三个域名#

框架选型是这次迁移里最容易的部分，难的在部署。难的原因要从 landing 的一个小功能说起。

landing 首页有一个”最近文章”列表。它最简单的实现是构建时生成：一个脚本读 posts 里每篇文章的 frontmatter，丢掉草稿，按标签过滤，中英文孪生取英文版，按发布日期取前五篇，写成一个 JSON。它被接进 landing 的 dev 和 build 命令里，每次构建都重新同步：

1
"dev": "node scripts/sync-posts.mjs && astro dev",
2
"build": "node scripts/sync-posts.mjs && astro build",

构建期耦合是好耦合：产物是纯静态的，没有运行时 fetch，没有 CORS，没有加载态，列表和博客同一天更新。但它有一个硬约束：landing 的构建必须读得到博客的源文件。两个站点，一个仓库，没有别的选项。这就是 monorepo 的由来。

然后 GitHub Pages 就出局了。它的发布模型是一个仓库对应一个站点：一个发布源，一个自定义域名。两个 project、两个域名的需求，在这个模型里没有对应物。

能想到的替代方案我都想过：

• 两个仓库，landing 构建时把博客 checkout 进来。跨仓 checkout 要带 token，构建顺序变成两个仓库之间的协调，而且博客推一篇文章不会触发 landing 重建，列表会一直停在旧的样子。
• landing 运行时去 fetch 博客的 RSS 或 JSON。首屏多一个加载态，landing 的可用性从此挂在博客的可用性上，和”静态产物、按需 JS”的整个前提相反。
• 一个站点，博客加路径前缀。一个站点装两种心智，base 路径和 CNAME 要跟着折腾，landing 和博客的生命周期从此绑死。

Cloudflare Pages 的模型正好是这个需求的形状：一个仓库可以挂多个 project，每个 project 指定自己的根目录、构建命令和自定义域名。于是现在的拓扑是：

flowchart LR
    P["push 到 main"]
    P --> W["Pages 构建触发<br/>dashboard 里配置"]
    W --> L["project: landing<br/>根目录 landing/"]
    W --> B["project: blog<br/>根目录 blog/"]
    L --> A["ansonate.ink"]
    B --> D["blog.ansonate.ink"]
    G["GitHub Pages<br/>发布源 docs/"] --> E["dev.ansonate.ink"]

部署链也换了主角。仓库里的 GitHub Actions 只做验证：astro check，再在 Node 22 和 24 上各构建一遍，没有 deploy 步骤。真正上线的那一下在 Cloudflare 那边：构建触发配在 dashboard 里而不是仓库里，push 到 main 就触发对应 project 的构建和部署。CI 管”代码对不对”，CF 管”站点活没活”，分工是清楚的，代价留在第 6 节说。

域名的分工：

第三个域名值得单独说。那十几个 SPA demo 各自是独立仓库，各自开着 GitHub Pages。GitHub 有个顺手的机制：用户站配了自定义域名（先配好 DNS 解析到 GitHub Pages）之后，同账号的项目站默认挂在这个域名的子路径下，所以这个仓库的 Pages 占住 dev.ansonate.ink，所有 demo 就都能以 dev.ansonate.ink/<repo>/ 的形式活着，主站的旧链接用 301 指过去。

这个 Pages 的发布源是 docs/，里面只有一个带 noindex 的跳转页。严格说它不放东西也行，demo 的存活不依赖根路径上有什么；但根路径本身总得有个着落，不然直接访问 dev.ansonate.ink 的人会撞上一个 404。现在这个跳转页把这一小撮人送去 ansonate.ink/apps 的 gallery。老东西一个没死，只是搬了家。

等等！老链接不能死#

迁移的完成标准是每一个旧 URL 都有着落，,因为我简历里填了老链接。旧站虽然小，但 URL 的种类不少：八篇文章、一个 feed、一个 about、十几个 demo 路径。

先处理文章。Jekyll 的默认 permalink 是 /:categories/:year/:month/:day/:title.html，所以旧文章地址长这样，够长的：

1
/mathematics/deep-learning/2026/10/16/desmos-and-calu.html

category 是我自由发挥的，其中有带空格的（htmx 那篇的 “Web Development”），浏览器实际请求的是 %20 编码后的形态。Cloudflare Pages 的 _redirects 支持占位符，一条规则同时匹配解码和编码两种形态：

1
/:category/programming/2026/10/07/htmx-tailwind.html  https://blog.ansonate.ink/posts/htmx-tailwind/  301

_redirects 有两份，因为规则按 project 生效，apex 的 project 看不到 blogs 的规则，反过来也一样。apex 那份（landing/public/_redirects）用绝对地址干活：旧文章和 feed 跨域 301 到 blogs 子域，demo 路径 301 到 dev 子域。blogs 那份（blog/public/_redirects）用站内相对路径，接住直接撞在博客域名上的旧链接。feed 单独一行：jekyll-feed 的产物是 /feed.xml，Astro 这边是 /rss.xml。

demo 路径是十三行精确跳转加两行小写别名，早年的仓库名大小写不规范，两种写法都得接住：

1
/resume-tailor/*  https://dev.ansonate.ink/resume-tailor/:splat  301
2
/credicheck/*     https://dev.ansonate.ink/CrediCheck/:splat     301

301 这个状态码要想清楚再用：浏览器和 CDN 会长期缓存它，写错一条，修复的生效时间就不归你管了。稳妥的顺序是先挂 302 跑几天，确认每个目的地都对，再改成 301。

_redirects 也有够不着的地方：它只管路径，不管域名。apps.ansonate.ink 到 ansonate.ink/apps 这种域名级跳转，得去 Cloudflare dashboard 写 Redirect Rule。这条现在记在 landing 的 README 里，因为后面大概率会找错地方。

Free Is Not Free#

这套拓扑不是免费的，账单如下。

两条构建链。GitHub Actions 验证一遍，Cloudflare 部署时再构建一遍。直接后果是 CI 绿了不等于上线了：CF 侧的构建失败只出现在另一个 dashboard 里，GitHub 上不会有任何红灯。版本也要在三处对齐：landing/package.json 的 engines、workflow 里写死的 pnpm 版本、CF 项目设置里的那一份。任何一处漂移，就是”本地能过、CI 能过、线上炸了”。

两份 lockfile，两组 dependabot，域名的 DNS。_redirects 是一张要维护的表，站点级路径（feed、about 这类）改版时要记得回来更新。还有一处不好安放的：Cloudflare 的 project 设置配在 dashboard 里，是整套东西里唯一不在版本控制里的一部分。它不多，但它让我每次想说”全部配置即代码”的时候都要打个折扣。

这套东西什么时候是过度设计：如果你只需要一个博客的话，GitHub Pages 加 Jekyll 或 Hugo 仍然是最省事的组合，故事到此为止，但直到当你开始为了”让另一个页面读到这些内容”而改造发布管道的时候。

结语#

2024 年那篇公告里，我写 Jekyll 完美适合我的偏好。那句话当时是真的，现在也不算错，只是语境变了：两年里我的用法长出了主题的形状，一个 landing、一组复用组件、一套双语约定，而工具停在原地。Jekyll 没有变差，是我对它提的要求变了。

这次迁移的实质，是我停止租用展示层。从 markdown 到 DNS，每一层现在都有名字、有版本、有我读得懂的报错。代价是自己修水管：两条构建链、三个域名、一份 redirect 表，外加一点藏在 dashboard 里的配置。

现在发一篇文章的动作是这样的：写完，push，两个 project 各自构建，landing 的”最近文章”自动换一版，老链接原地不动。整套流程里没有一步需要我记着什么，这大概就是两年前那个在正文里贴 include 的人想要的东西。

附：迁移清单#

给要做同样事情的人，按顺序：

1. 先盘点旧站的所有 URL：文章、feed、about、附件、demo，列成表。迁移完成的标准就是这张表全绿。
2. 选框架的判据排序：工具链是不是你的，JS 粒度，生态。性能 benchmark 排最后。
3. fork 主题，不要 hack 主题，除非你知道后面新东西不多。判断标准只有一个：主题的模板文件在不在你的仓库里。
4. 内容先于样式：先定 frontmatter schema、content collections 的位置、多语言约定，再谈好不好看。
5. 站点间共享内容用构建期脚本，显式、可 diff，不要用运行时 fetch。
6. 确认托管方支持”一个仓库多个 project、按目录构建”，这是 monorepo 的前提。
7. 验证和部署分开：CI 只验证，部署交给托管方的 push 触发，但要接受”绿灯不等于上线”。
8. redirects 先 302 后 301；带空格的旧路径用占位符，两种编码形态都要测。
9. 查清 _redirects 的能力边界：不管域名、有规则条数上限，域名级跳转移交 dashboard。