Stellar：v2 迁移指南

本页介绍从 Stellar 1.44.0 升级到 v2 的步骤。使用更早版本时，还需查阅原版本到 1.44.0 之间的发布记录。v2 的配置结构有较大变化，旧配置需要转换后才能使用。

备份站点与主题

记录当前主题版本或 commit、Node/Hexo 版本和安装方式，保存锁文件、站点配置、Collection 文件、文章 Front Matter 及主题定制。使用 Git 时，也要保留尚未提交的修改，以便恢复升级前的站点。

按字段映射查找站点中使用的旧配置。逐处确认用途，避免批量替换误改正文示例、第三方参数或历史记录。

除字段名称外，还要记录文章 URL、评论对应的讨论、Collection ID、图片用途和自定义脚本。部分默认行为已经变化，可能需要显式配置才能保持原有效果。站点、主题定制和独立文档仓库中的文件应分别处理。

在 _config.stellar.yml 中填写需要覆盖的 v2 配置，按字段映射逐项转换。主要变化包括：

Brand 的文字、图片和链接拆成独立字段，文字中不再嵌入 HTML 或 Markdown 链接。
顶部栏和左右栏使用对象配置，组件列表写在 widgets 数组中。
文章与集合的字段按内容类型区分，卡片封面、内容横幅、Hero 和头像分别配置。
第三方服务参数保留原来的字段名；主题不再支持的资源路径和内部缓存设置需要移除。
v1 的 about、users 标签，chat_users.yml、fcircle 适配器及已移除的标签配置字段，按标签与动态数据迁移表逐项替换或删除。

没有直接替代字段的功能，需要根据原用途选择新的实现方式。页面归属、路由或评论标识尚未确认时，暂时保留原文件，查清后再修改。

npx hexo stellar doctor
npx hexo generate

修复 Doctor 报告中的错误，并逐项检查警告。对比站点中使用的文章、Wiki、专栏、笔记本及自定义页面，确认搜索、评论和导航仍可用。

若构建还包含 Babel 或压缩步骤，需要运行站点完整构建，并确保 public/js/runtime/**/*.js 保留原生 ESM 和相对导入。

页面 URL 改变时，为旧地址设置到最终地址的跳转，同时检查章节锚点、canonical、站点地图和内链。静态跳转页与服务器 HTTP 301 的处理方式不同，应按托管平台支持的方式配置。

本套文档的路径与锚点映射表记录了旧页面和章节的新位置，由本站生成跳转页；旧正文仍可在 Git 历史中查阅。

保存修改清单、重要配置变化、检查结果和未解决的问题。需要回退时，同时恢复旧主题版本、站点文件和配置；只降级主题包无法恢复使用 v2 配置的站点。

使用 AI 协助时，可以把AI 迁移步骤与站点仓库一起提供。提交、推送和部署等操作按你的授权执行。