故障排查

如果问题出现在从 3.x 升级期间，请先完成升级到 4.0中的全部步骤，再逐一排查功能模块。

构建与配置

1. 运行 hexo clean 并重新生成。
2. 检查两个配置文件的 YAML 缩进。
3. 将主题顶层键与 v4.0.0 默认配置逐项比较。
4. 只关闭最近启用的模块并复现错误。

ES 模块与 CDN

• 确认 main.js 通过 type="module" 加载。
• 在浏览器网络面板定位第一个失败的动态导入。
• 确保所有主题内部文件来自同一 Solitude 版本。
• 自定义 CDN 必须保留完整的 source/js/ 相对目录树。
• 不要把模块 URL 重写成彼此独立的扁平文件名。

PJAX 资源累积

在相同两个页面间反复切换。重复弹窗、播放器、回调或网络请求通常表示自定义代码在每次 afterNavigate 都注册永久资源。应只订阅一次，再使用浏览器 API中的页面级清理方法。

数据与集成检查

• 确认 YAML 数据是功能指南要求的数组或对象，不要添加通用 items 包装层。
• 友链异步模式启用时检查 /links.json。
• 排查本地搜索界面前先确认 /search.xml。
• 从部署域名测试服务地址和域名白名单。
• 最近评论与 PV 统计只能使用对应模板支持的评论服务。

提交问题时请提供 Solitude、Hexo、Node 版本，移除密钥后的相关配置，生成页面 URL，以及第一条控制台或网络错误。