每处按「症状 → 根因 → 改法」记录，文件与关键取值都保留。

1. 卡片外壳不统一

症状：首页卡片 8px 圆角、侧栏 4px、音乐馆又是另一种。

根因：各处各写各的圆角、边框、阴影，没有公共变量。

改法：site-inject.css 末尾立 token，其余容器挂上去。

1
2
3
4
5
6
7
8
:root {
  --ucard-r: 16px;
  --ucard-bd: rgba(128, 128, 128, .16);
  --ucard-shadow: 0 2px 10px -7px rgba(7, 17, 27, .35);
}
[data-theme="dark"] {
  --ucard-bd: rgba(255, 255, 255, .13);
}

覆盖 #recent-posts .recent-post-item、#post、#page、#archive、#aside-content .card-widget、.mp-card、.tk-submit。只有列表卡加悬停上浮，大容器不加。

2. 评论气泡

症状：评论内容是主题色实心底，字压在上面，且与其他卡片不搭。

根因：Twikoo 自带样式优先级较高。

改法：twikoo.css 末尾只改 .tk-content，玻璃底 + 左侧 3px 主题色竖线；另加一行 .twikoo .tk-footer { display: none !important } 收掉署名。

不修改 twikoo.all.min.js，避免升级冲突。

3. 关于页

原页是主题默认自述模板，换人即失效。改为 source/about/index.md 手写三段式：铭牌、工艺卡、实时体检，类名统一 .ab2-*。地址从 /personal/about/ 迁到 /about/，旧路径直接 404，站内链接全部替换。

4. 字体缺字

症状：同一段里部分字变成系统字体。

根因：字体文件字集不全，缺字回落。

改法：_custom/custom.css 的 @font-face 做三级 src：本机 → @fontsource CDN → source/fonts/*-substitute.woff2 兜底；tools/font-subset.js 裁剪兜底字体。

5. /tags/ /nav/ 整页发粉

症状：只有这三页泛粉。

根因：专属样式把大面积容器的底色和描边用 color-mix() 从主题色派生，而默认主题色实际是 #FF1493。

改法：大面积底色改中性，主题色只留在线条、角标、下划线。涉及 stats.css、stats.js、nav/index.md、links/index.md。

6. 页面留白不一致

以音乐馆为基准，用 vw 与 clamp() 换算后统一到其他页面；首页保留自身比例。

7. 缓存

所有资源引用带 ?v=，改一次推一位。页面级写在 front-matter 或模板，全站写在 inject 段。改 .pug 需重启 hexo server。

8. pjax 三类故障

8.1 运行期链接整页跳
根因：pjax 只拦截初始化时存在的 <a>。
改法：pjax-relink.js 在 pjax:complete 后重扫并绑定。

8.2 进页后滚动失效
根因：scrollFn() 读到旧高度，命中"不足一屏 return"。
改法：inject/nav-scroll-rebind.js 在 pjax 后补调 refreshFn()。

8.3 顶栏闪烁
根因：scroll 靠等值判断方向，wheel 回调回写了 position，等值被顶掉。
改法：scroll 保留 if (scroll === position) return；wheel 回调禁止回写 position。

9. 音乐跨页中断

根因：整页导航销毁 music-bus.js 闭包，<audio> 随之消失。

改法：站内跳转全走 pjax；整页刷新用 sessionStorage.fomalPlayerResume 存快照，新文档读回并 seek。快照记录 wantPlaying，不读 audio.paused。

10. 加密文章解锁

根因：hexo-blog-encrypt 锁屏只有输入框，解密依赖回车事件，焦点不在框内即失效。

改法：unlock-secret.js 增加按钮，接管点击、回车、移动端；解密后补做目录重算与图片懒加载。

11. 部署链路

由"推源码"改为"推成品"：_config.yml 的 deploy 指向成品仓库，hexo d 只推 public/；项目 git 的 origin 移除，避免误推源码。

前提是托管平台能直接吃静态产物。若平台仍执行 npm run build 而仓库无 package.json，构建失败，站点停在上一版。发布后需确认线上 Last-Modified。

12. 改动文档

docs/站点改动总览.md 规定每次改动写五项：症状、根因、改动文件与行、验证方式、回滚与注意事项。