升级到 4.0

本指南适用于已有的 Solitude 3.x 博客；新建博客请阅读安装。迁移清单以官方 v3.0.20...v4.0.0 比较为基线。开始前请备份博客源码和配置。

1. 更新主题

请沿用博客当前的主题安装方式：

npm install hexo-theme-solitude@4

git -C themes/solitude fetch --tags
git -C themes/solitude switch --detach v4.0.0

2. 合并主题配置

按照安装中的说明重新复制一份 Solitude 4 默认配置，再将自己的定制值合并进去。不要使用旧 3.x 配置覆盖新文件。

重点检查以下新增或变更项：

• page.links.async_threshold 控制友链异步渲染阈值。
• theme_color.nav_hover_text.light/dark 控制导航悬停文字对比度。
• search.ai.enable 和 search.ai.url 为本地搜索增加外部 AI 入口。
• right_menu.custom_list[].click 应调用 Solitude.randomPost() 或其他公开的 Solitude 方法。

3. 迁移自定义 JavaScript

将调用 pjax.loadUrl、utils.getScript、utils.getCSS、GLOBAL_CONFIG 或 PAGE_CONFIG 的自定义代码迁移到浏览器 API 中的公开方法。不要基于 sco、rm、ai、coverColor 等内部全局对象开发扩展。

自定义模板应通过 data-solitude-action 调用注册在 window.Solitude 上的函数，避免注入内联事件处理器。

4. 检查 CDN 与自托管

浏览器入口是原生 ES 模块。通过 CDN 或其他主机提供 Solitude JavaScript 时，必须发布同一主题版本的完整 source/js/ 文件树并保留相对路径；只上传 main.js 会导致相对导入失败。

5. 清理、重新生成并测试

hexo clean
hexo generate
hexo server

反复通过 PJAX 访问首页、文章、归档、友链和音乐页，并测试已启用的搜索与评论、明暗模式、右键菜单、自定义模板以及浏览器前进后退。如有检查项失败，请继续阅读故障排查。