1. 先确认上游版本#

我先拉了上游 Mizuki 仓库的最新分支和标签，然后确认当前上游主线的 package.json 已经是：

1
{
2
  "version": "9.0"
3
}

也就是说，这次升级的目标不是 8.x 的小修小补，而是正式进入 9.0。

2. 用上游 9.0 替换主题主体#

替换时我没有动这些目录：

• content/
• src/content/
• src/data/
• public/images/

原因很简单，这几块都和我现有的内容仓结构绑定在一起，尤其是：

• src/content/posts
• src/content/spec
• src/data
• public/images

它们本身就是通过链接映射到 content/ 下的真实内容目录。
如果把这些一起覆盖，文章、数据和图片组织方式会先乱掉，后面的迁移成本会陡增。

3. 把本地配置迁到新的配置结构里#

这一版升级里，最需要人工处理的地方其实是配置文件。

旧版配置还能表达这些内容：

• 站点基础信息
• 主题色
• 导航链接
• Sidebar 组件顺序
• 评论系统
• 音乐播放器
• TOC 行为

但在 9.0 里，很多配置项的组织方式已经变了，比如：

• Sidebar 的组件布局从旧式写法切换到新的结构化配置
• TOC 的模式字段换成了更细的开关组合
• 音乐播放器多了 showFloatingPlayer 之类的新字段
• 文章页增加了随机文章和相关文章等配置项
• 第三方统计部分也拆得更清晰了

所以我没有继续硬撑旧配置，而是直接按 9.0 的结构重写了配置，再把自己的站点信息迁进去。

这一步实际保留了这些本地内容：

• 站点标题与副标题
• Harena 的导航菜单
• Twikoo 评论地址
• Clarity 统计配置
• 头像、Logo、favicon 路径
• 原来的页面开关策略

4. 保留内容分离和链接同步能力#

我这个仓库不是把所有文章都直接塞在主题代码仓里，而是保留了内容仓分离的习惯。
这套结构的好处是：

• 代码和内容职责更清楚
• 文章迁移更容易
• 主题更新时不容易误伤内容

为了让这套方式继续工作，升级后我仍然保留了内容同步脚本的行为，并且继续让这些路径自动链接到 content/：

1
src/content/posts -> content/posts
2
src/content/spec  -> content/spec
3
src/data          -> content/data
4
public/images     -> content/images

这样升级主题时，文章本身不需要跟着大搬家。

5. 最后用检查和构建收口#

代码替换完之后，我没有直接提交，而是先跑了三类验证：

1
pnpm check
2
pnpm build
3
pnpm lint

其中真正决定迁移是否完成的，是前两个：

• pnpm check 用来确认类型和内容 schema 没问题
• pnpm build 用来确认主题能完整构建

这一步可以非常快地暴露出“看起来升级了，实际上站点已经坏掉”的问题。

1. 组件结构明显更模块化了#

旧版里很多组件是按页面和功能混排的。
而在 9.0 里，组件被更明确地拆成了几类：

• atoms
• features
• widgets
• organisms
• layout
• misc

这种调整的直接好处是：

• 目录职责更清晰
• 找组件更快
• 二次定制时更容易判断改哪一层

如果你以后还会长期维护自己的站，这种重构其实很值。

2. Sidebar 和布局系统更成熟了#

这是 9.0 最明显的一类变化。

新版本把侧栏组件顺序、左右分布、抽屉内容这些东西都收敛到统一配置里，意味着：

• 左右侧栏怎么排，不再靠散落逻辑硬拼
• 移动端抽屉和桌面侧栏能统一管理
• 组件启用与顺序更容易维护

对主题使用者来说，这种变化不一定第一眼能看见，但长期维护时会非常舒服。

3. 文章页能力更完整了#

9.0 在文章页上增加或补齐了不少能力，比如：

• 更完整的文章信息组件
• 相关文章
• 随机文章
• 更细的 TOC 组件拆分
• 分享卡片与文章周边模块的组织优化

如果只是“写博客”，这类变化会直接体现在可用性上。

4. 工具链升级到更现代的组合#

从依赖上看，这一版也明显做了现代化处理，包括：

• Astro 6
• @astrojs/svelte 8
• 更新的 Svelte 5 生态
• ESLint/Prettier 工作流替代旧的 Biome 工作流

这说明上游在继续整理工程工具链，而不是只堆页面功能。

5. 文档比以前完整得多#

这个版本新增了不少规则文档和性能相关文档，例如：

• 组件架构
• 文件组织
• CSS 规范
• Sidebar Widget 开发说明
• 性能监控与基线

对“拿来就用”的用户来说，这些文档不一定马上会看。
但对要做深度定制的人来说，这其实是非常实用的升级。

保留旧站的品牌资源#

上游这版默认更偏向使用 webp 资源，但我站里原本已经有自己的：

• home.png
• default-logo.png
• favicon.ico
• avatar.webp

所以我没有强行全部换成上游默认资源，而是继续保留了自己的站点识别资源。

让 GitHub Actions 继续适配 main#

上游新的工作流默认监听的是 master。
但我的仓库默认分支是 main，如果直接照搬，CI 很可能根本不触发。

所以我把工作流监听分支改成了同时兼容：

1
branches: [ main, master ]

这类细节不算“主题功能”，但非常影响实际使用。

关闭我不打算立即启用的新功能#

9.0 增加了新的文章页组件和一些额外功能，但我这次迁移的目标是“稳定升级”，不是“顺手改版”。

因此像下面这些新增能力，我先做了保守处理：

• 随机文章：先关闭
• 相关文章：先关闭
• 新的音乐浮动入口：保留配置但不启用

这样能保证升级之后的界面变化尽量可控。