9 月 3 日把博客主题 Stellar 从 1.33.1 升到 1.44.0，本以为是一行 npm install 的事，最后变成两天、十一轮对齐：以线上 1.33.1 为基准，一页一页、一块一块地比，9 月 4 日发布上线。
这篇记录改了什么，踩了什么坑。
为什么升级
1.34 到 1.44，中间隔了十个版本。左侧栏重构过，横幅改版过，专栏卡从横排改竖排，配置键有删有改。拖得越久迁移成本越大，堆在 1.33.1 上的那些自定义样式，迟早要一笔一笔还。
不如趁现在。
一条原则：不动主题源码
整个升级过程只守一条原则：不改主题源文件，所有定制走主题的 inject 机制，把自定义 CSS/JS 注入页面。
好处是下次升级不带任何私货，直接换新版本。代价是注入清单越来越长：升级前 8 个文件，升级后 12 个，新增 leftbar-order.js、leftbar-extras.js、leftbar-extras.css、topic-card-link.js。
配置迁移
先把配置文件过一遍，删废弃键、换改名键：
style.smooth_scroll删掉，滚动体验改由 JS 统一控制font-size.body删掉，正文字号从 root 派生；为了保住原来正文 17px 的观感，root 取 17pxcomments.lazyload删掉，artalk 图片弹窗 1.44 起内置animated_avatar.background挪到style.gradient.avatar- 左侧栏纯色背景按明暗拆成两个键
- CSS 变量
--gap-margin改名--gap-base - icons.yml 里 5 个图标键是 1.41 改过名的，逐个补回来
另外把 1.44 的两个新默认刻意压了回去：pin_style: flat（置顶文章不变轮播大卡）、card_style: classic（文章卡不变全图封面大卡）。新样式会让卡片跑到 navbar 上面、变得更宽，和线上既有版式对不上。
视觉对齐
最重的一块。版本一升，样式到处变，照着线上 1.33.1 逐个对齐：
- 侧边栏透明化，菜单位置移回原位，五个导航图标像素级对齐（容器 40px，图标 28px）
- 导航栏全透明，当前项换成 32px 松绿药丸
- 卡片 hover 浮起阴影、暗色主题色透光，按 1.33.1 原值补回
- 侧边栏和日历卡片加 1px 流动高光，6 秒顺时针转一圈；两处采样同一个角度变量，保证转动同步
插曲：第八轮顺手给菜单栏也加了高光，实测发现没必要，第九轮又去掉了。这种先加后减的来回，占了不少轮次。
专栏卡整卡可点
1.44 的专栏卡只有封面链接能跳，跳的还是最新文章，这是个退化（1.33.1 整卡可点）。解法是 topic-card-link.js 读 search.json 建一张标题到总览页的映射表，重写 href，再用 ::after 伪元素铺满整卡接管点击。
踩了个坑：起初把 pointer-events: none 写在 .cover::after 上，位置尺寸全对，点击却穿透了。查下来，主题本来就对这个伪元素写了样式，要覆盖必须显式写 pointer-events: auto。教训记下了：覆盖伪元素之前，先看主题对同一个伪元素写了什么。
移植两个功能
1.33.1 上有两个自己做的交互，升级时原样搬了过来：
- 侧边栏收起：收起后变 64px 窄栏，本质是把侧边栏宽度变量归零，状态存 localStorage
- 弹层搜索：整个 #search-wrapper 搬过来，复用主题的监听
遇到两个 Chromium 的坑：
- 弹层刚可见就调 focus() 会被拒，改成 40ms 一次的重试循环
- 输入框搬进关闭的弹层后不可聚焦，得在捕获阶段抢在主题前面处理
后三轮打磨
第九到十一轮，都是小修：
- 专栏卡上有个主题伪元素视觉层跟着铺满了整卡，清掉
- 卡内文章列表改时间升序，集数作第二排序键
- 带背景图的文章，把隐藏的横幅面包屑克隆到 banner 顶行；首页不受影响
- 页脚图标换了一批，公益 404 换成腾讯寻梦
- 确认分页 per_page=10，只有一页时不渲染翻页器；临时改成 2 验证过，再改回来
专栏改名
顺手把专栏名从「Hexo 教程」改成了「博客搭建记录」。写的其实不是教程，是搭建和维护的记录，名字跟着实际走。URL 不变，还是 /topic/hexo-tutorial/，外链不会失效。
结果
9 月 4 日发布上线，所有变更在备份仓库开了 PR 合进主线：128 个文件，新增约 1.2 万行。
算下来：两天，十一轮，12 个注入文件，截图存档 40 多张。花功夫最多的不是写代码，是对照，一页一页、一块一块跟旧版本比，每条结论都复现过才敢改。