第三代博客：Astro + Firefly 的迁移与改造记录
本文由 AI 根据建站过程中的实际改动整理生成，可能存在表述偏差或遗漏；请以仓库中的真实代码与配置为准。
本站已迭代到第三代：WordPress → Hexo + NexT → Astro + Firefly。本文只记「为了把主题变成自己的站」实际动过哪些地方，方便以后升级上游时对照，不当作通用教程。
为什么再换一次
前两代各自解决过当时的问题：WordPress 上手快、后台可视化；Hexo 静态部署省心，NexT 也改得顺手。换 Astro 主要不是为了「更好看」，而是扩展性：
| WordPress | Hexo + NexT | Astro + Firefly | |
|---|---|---|---|
| 写文 | 后台编辑 | Markdown | Markdown / MDX |
| 交互 | 插件 / PHP | 嵌脚本别扭 | 岛屿组件，局部 React/Svelte 自然 |
| 运维 | 服务器与更新 | hexo g && deploy | pnpm build + 静态托管 |
| 适合 | 早期个人站 | 论文笔记 + 机制文 | 博客 + 以后挂小工具 |
机制计算器、文内嵌组件这类需求，在 Hexo 里硬塞主题不如在 Astro 里直接做页面。Firefly 基于 Fuwari，配置集中在 src/config/*，多数「换皮」不用先动源码。
官方文档：Firefly Docs。
改动分层
| 层级 | 做什么 | 典型路径 |
|---|---|---|
| 配置 | 站点身份、导航、页面开关、评论、壁纸 | src/config/*.ts |
| 文案 / 资源 | About、Favicon、头像、演示文清理 | src/content/spec/、public/、src/assets/ |
| 主题小改 | 表格、目录、About 公式、Dark Reader | markdown.css、toc-*.ts、about.astro、Layout.astro |
| 内容 | 旧文迁移与 frontmatter 对齐 | src/content/posts/、scripts/wp_to_md.py |
原则：能配就不改主题；只有默认行为卡住正文排版时，再动 CSS / 工具函数。
一、配置层：从 Demo 变成个人站
站点身份
主要在 siteConfig.ts / profileConfig.ts：
- 标题、副标题、描述、关键词换成自己的文案
site_url先指向现有域名（后续可随正式上线再改）siteStartDate接到更早的建站日期，页脚运行天数才有意义- 主题色相、卡片边框 / 跟随主题色、文章卡片摘要行数、瀑布流等按阅读习惯微调
- 提醒框主题改为 VitePress 风格（
rehypeCallouts.theme），和论文笔记里的 callout 观感更贴近 - 头像、导航 Logo、Favicon 换成自己的图（Favicon 需落在
public/下才能被浏览器正确加载）
页面与导航做减法
Firefly 默认打开友链、打赏、番组、相册、追番、动态等。本站暂不需要，在 siteConfig.pages 里关掉对应开关；导航里主题自带的「链接」子菜单也注释掉，避免首页还像官方演示站。
侧栏改为偏左侧布局，关掉公告组件，减少干扰。
评论：Twikoo
评论与站点托管可以分开部署。前端在 commentConfig.ts：
type: "twikoo"envId必须是自己的云函数地址，不能用官方演示twikoo.vercel.app
Firefly 对 Twikoo 有现成主题样式，观感比硬改 Waline 省事。后端仍需自建（常见是 MongoDB Atlas + Vercel / Netlify 等），部署成功页应显示「Twikoo 云函数运行正常」，再把该 URL 填进 envId。
字体等杂项
按个人喜好在 fontConfig.ts 增加了 Lato；壁纸、页脚 HTML、音乐等也在对应配置里换成自己的资源或文案。这些都属于「换皮」，升级上游时冲突通常好解决。
二、主题小改：几处真正动到的代码
配置解决不了、又直接影响阅读体验的，目前主要是下面几处。
1. About 页公式：补上 KaTeX 样式
About 写在 src/content/spec/about.md，可以用 $...$ / $$...$$。文章页会引入 KatexManager（加载 katex.min.css），About 页原先没有，于是可见的 HTML 排版和无障碍 MathML 叠在一起，公式看起来像重复了一截。
处理：在 src/pages/about.astro 与文章页对齐，加上：
<KatexManager slot="head" />以后凡是走 spec 或自定义页面、又要用数学公式的，都要确认是否引入了 KatexManager，不要只以为「Markdown 里写了公式就会自动漂亮」。
2. 表格：按容器宽度自适应
指挥喵等机制文表格列数多。Firefly 默认大致是：
- 表格
width: max-content - 单元格
min-width: 120px
结果很容易超出正文栏，再被包进横向滚动容器。论文 / 数据表更希望「铺满卡片宽度、长文换行」。
在 src/styles/markdown.css 中调整为：
- 表格
width: 100%，随正文宽度走 - 去掉强制
min-width: 120px，允许列收缩 overflow-wrap: anywhere处理超长单元格- 尊重 Markdown 对齐语法生成的
align="center|left|right"（原先全局text-left会盖掉:---:） - 表格内图标统一
inline-block+ 垂直居中，仅含图标的列适当收窄
若某篇极宽表仍想横向滚动，可以再局部覆盖；当前默认优先适配本站常见的多列表格。
3. 目录：排除 GFM「Footnotes」
论文笔记大量使用 [^slug] 脚注。GFM 会在文末自动插入类似：
<section class="footnotes"> <h2 id="footnote-label">Footnotes</h2> ...</section>侧栏 TOC 会收集正文标题，于是目录末尾多出一个英文 Footnotes，和手写的「参考文献」叠床架屋。
在 toc-shared.ts（构建期 headings）和 toc-utils.ts（客户端收集标题）里，把 footnote-label / 文案为 Footnotes·脚注 / .footnotes 内标题从目录中滤掉。正文脚注列表仍保留。
4. Dark Reader：官方 lock
Firefly 已自带亮 / 暗色主题（html.dark、半透明 overlay、彩色 callout 等）。若访客同时开启浏览器扩展 Dark Reader，扩展会再染一遍颜色，容易出现壁纸半透明层发黑块、Admonition 色调发脏等问题。
处理很轻：在 Layout.astro 的 <head> 加入 Dark Reader 官方 opt-out：
<meta name="darkreader-lock" />扩展识别到后会对本页停用动态改色，无需再做检测弹窗。站点暗色仍用主题内置开关即可。
三、内容迁移
Frontmatter 要对齐 Firefly
Hexo 常见字段和 Firefly 不完全一致，迁移时统一成例如：
title: ...published: YYYY-MM-DDdescription: ...category: ...tags: [...]slug: ...draft: false注意：categories → category；日期用 published 而不是 date；摘要优先写在 description，不必依赖 Hexo 的 <!-- more -->。
提醒框尽量用主题已支持的 callout（如 [!NOTE]），少依赖旧主题的 HTML 标签。行内小图标、彩色标注等，在 Markdown 能力不够时仍可用少量 HTML，但尽量把「样式规则」收到主题 CSS，避免每篇文章复制内联 style。
来源与脚本
- Hexo 文：按篇迁到
src/content/posts/，并按上面格式整理（量化笔记、MD5 笔记、碧蓝机制文等）。 - WordPress 导出（WXR）：用仓库内
scripts/wp_to_md.py转成 Markdown（处理 Gutenberg 块、[latex]、[crayon]等），再人工扫一遍草稿与空文。
主题自带的演示文章已挪到 firefly_draft/ 或不再作为正式内容展示，避免首页仍像官方 Demo。
图床外链（如长期稳定的图床 URL）可继续用；旧 WordPress 域名下的图片若站点已下线，需要另迁，本文不展开。
四、部署侧（与主题改动正交）
- 构建：项目要求 pnpm；
pnpm install && pnpm build，产物在dist。 - 静态托管即可（GitHub Pages、EdgeOne Pages、Netlify、Vercel 等）；不要为了纯静态站误开仅 Cloudflare Workers 才需要的环境变量。
- 站点托管 ≠ 评论后端：博客在 A 平台、Twikoo 在 B 平台完全可行。
具体域名与 CDN 以实际上线配置为准；换域名时记得同步 site_url 与评论回调相关设置。
五、升级上游时怎么复查
从上游 Firefly 拉新版本时，建议优先核对：
src/config/*是否被示例配置覆盖（用自己的配置文件或合并工具仔细 diff）markdown.css表格相关规则是否被还原toc-shared.ts/toc-utils.ts的脚注过滤是否还在about.astro是否仍引入KatexManagerLayout.astro是否仍含<meta name="darkreader-lock" />commentConfig的envId是否仍指向自己的后端
内容目录与 scripts/wp_to_md.py 一般不在上游范围内，冲突较少。
小结
这轮迁站的过程中，大部分工作是配置与内容，真正改主题源码的主要是：About 补 KaTeX、表格自适应与对齐、TOC 排除脚注标题，以及 darkreader-lock。其余是关掉用不到的页面、换上自己的身份与评论后端、把旧站 Markdown / WXR 收进 Firefly 的 frontmatter 约定。
文章分享
如果这篇文章对你有帮助，欢迎分享给更多人！