博客从 Hugo 搬到 Navfolio：一次完整的折腾记录

博客换主题了。从 Hugo + PaperMod 搬到了 Astro + Navfolio。这篇把整个过程记下来，包括为什么换、怎么迁、踩了哪些坑。

为什么换

PaperMod 很好，轻量、快、简洁。但用了一段时间发现，它是个纯粹的博客主题——文章列表 + 文章页，别的就没了。

Navfolio 不一样。它的定位是”个人仪表盘”：首页是一个 dashboard，头像、座右铭、导航卡片、写作统计、热力图都在一屏里。博客只是其中一块。这更符合我想要的——博客不只是一个放文章的地方，是个人在网上的一个据点。

另外做个澄清：个人门户和博客是两个网站、两个仓库。门户以后再说，这篇只讲博客。

迁移的第一原则：URL 不变

这是整个迁移里最重要的一条。旧博客的文章地址是 /post/<slug>/ 这种格式，评论系统 Giscus 是按 pathname 绑定评论的——也就是说，只要新站的文章 URL 和旧站一模一样，老评论会自动续上，不用迁移数据库。

所以迁移时第一件事就是确认新主题的文章路由能配成 /post/<slug>/，并且带 trailing slash。配完了一篇篇对，中文英文都要对。

双语架构

中文是默认语言，直接走根路径 /；英文走 /en/。这个设计有几个细节：

• 首次访问自动跳转：根据浏览器语言决定进中文还是英文，但爬虫排除在外（不然搜索引擎收录会乱）
• 手动选择会被记住：用 localStorage 存下来，下次直接进上次选的语言
• 切换语言跳对应译文：在中文文章页点 EN，会跳到那篇文章的英文版；如果那篇文章没有译文，才回退到首页
• 搜索索引中英分离：用 Pagefind，中文和英文各建一个索引，搜中文不会冒出英文结果

首页：被打回的那一版

一开始图省事，首页做成了普通博客样式——标题加文章列表。被我自己打回了：跟官方演示站的仪表盘风格差太多。

重做时直接用了官方的组件：ProfileCard（头像+名字）、IntroCard（座右铭+介绍）、NavigationCard（导航卡片）、ConnectCard（社交链接）、BlogHeatmap（写作热力图），按官方的排版拼成 dashboard。配了中英两套文案。

中间还出过一个小 bug：标题显示成”你好，你好，我是 Sloan Sloan Gray”——greeting 和 title 重复了。修掉就好。

字体：WenKai + Maple Mono

中文字体换成了 LXGW WenKai（霞鹜文楷），英文和 UI 用 Maple Mono 等宽字体。这套组合就是主题的”纸+打字机”味道，文楷的书卷气配等宽字体的技术感，跟”拆开世界再装回去”的座右铭挺搭。

技术细节：文楷的 TTF 有好几 MB，构建时做了 subset 切分，只打包用到的字符，加载没问题。文楷只有一个 Regular 字重，中文加粗是浏览器合成的，实际看标题渲染可以接受，就没再折腾。

结论：字体调到”顺眼且有辨识度”就收手，再往下是玄学。

头像：居中裁切

头像用的我自己的照片。原图是竖构图的人像，第一版按人脸位置裁的，被我否了——改成从正中间向两边延伸的居中正方形裁切。人物在正中间，构图稳。

favicon：SGX 三字母标

一开始没想到用什么，生成了几个方案：S 字母、墨点、折纸。最后定的方向是 SGX——Sloan Gray 的首字母，也是 styrigx 的核心三个字母，名字和用户名都代表了。

设计过程走了几轮：第一版是衬线 S，太普通；第二版是 S/G/X 笔画互锁的几何标，有设计感但缩到小尺寸认不出字母；最后在互锁的基础上加粗笔画、拉开字母分界，辨识度和设计感平衡。颜色用的鼠尾草绿，跟主题配色一致。

有个坑：主题优先引用 favicon.svg，我一开始放了个简版 SVG，结果浏览器标签页显示的不是定稿的互锁版。最后直接删掉 SVG，让浏览器降级用 PNG 版。

页脚年份：2020-2026，自动走

页脚原来是 © 2026 Sloan Gray，改成了 © 2020-2026。2020 是我开始上外网的年份，有纪念意义。

年份的后半截是自动的——代码里取构建时的当年年份，每次部署自动往后滚，不用手动改。只有一个前提：它是构建时算的，如果一整年都不部署，会一直显示旧年份。不过平时发文章就会触发构建，实际用起来就是自动的。

「最近」模块

官方演示站的关于页有个 “Recently” 板块，列最近在折腾的事。主题自带了 DoingCard 组件，只是默认没配数据、没接到页面。

我配了中英各 5 条，写的是真实在做的事：博客迁移、门户换主题、Muse 玩法手册、邀请码站、S26 换机计划。以后更新直接改配置里的 doing 列表就行。

部署：推代码就自动上线

之前是本地构建完手动 wrangler 直传，跟 GitHub 完全脱节。现在恢复成 Hugo 时代的全自动流程：

1. 源码在 styrigx/styrigx-blog，main 分支
2. push 后 GitHub Action 自动跑：安装依赖 → 构建（含字体切分、Pagefind 索引）→ wrangler 部署到 Cloudflare Pages
3. 以后写文章、改配置，push 一下就行

踩过的坑

几个值得记的：

1. NAVFOLIO_CONTENT_SOURCE=docs 是个雷。主题的 GitHub workflow 里默认带这个变量，会让构建用主题演示内容覆盖你的真实内容。如果走 Action 部署，必须删掉它。

2. wrangler 部署的环境变量。直传脚本要保留代理变量（http_proxy 等）和证书变量（SSL_CERT_FILE），不然 npm 下不动、wrangler 连不上。

3. TOML 子表的位置。[params.xxx] 这类子表必须放在同级普通 key 之后，否则后面的 key 会被吞进子表——之前因此丢过一次评论区。

4. Giscus 的参数别动。repo_id、category_id 这些一旦变了，老评论就对不上了。迁移时只动 URL 结构，不动评论配置。

5. 构建时年份 vs 运行时年份。页脚年份是构建时算的，理解这一点就不会困惑为什么”自动”还要依赖部署。

整个迁移一天搞定：上午定方案、下午迁内容、晚上调首页和图标、深夜上线。现在 https://styrigx-blog.pages.dev 跑的就是这套。

下一步是门户网站换主题，博客这边先稳定跑着。