换文字和链接#

• identity / title / subtitle：卡片上三行字，留空会自动回退到 profileConfig 和 siteConfig 里的名字、站点标题、签名
• navLinks：卡片标题下方的快捷导航，数组每一项 { name, url }
• socials：彩色标签社交按钮，最多 5 个，颜色按顺序自动循环。url 是跳转，copy 是点击复制（邮箱、微信号这种就适合用 copy）

改贴纸#

场景贴纸每一项的字段含义：

纵向用 top 还是 bottom 取决于贴纸在哪一排：底部那排全部用 bottom，这样无论贴纸多高，脚都踩在同一条线上；左右两列的上半部分用 top。

还有一个 1.25 倍的全局缩放系数在组件里（HomeWallpaperDecor.astro 顶部的 STICKER_SCALE），想要所有贴纸一起变大变小改它就行，不用一个个调 width。

替换素材#

新贴纸丢进 public/images/home-stickers/，然后改对应条目的 src。两个注意点：

1. 图片别太大——贴纸实际只显示 100~140px 宽（配置里的 width 再乘组件顶部的 1.25 倍缩放），源图 192px 宽就够，太大只会白烧流量
2. 底部一排的贴纸如果新素材身高差得特别大，地面线是靠 bottom 锚定保证的，不用管高度

关闭整套装饰#

enable: false，组件整个不渲染，默认的横幅文字会自己回来，什么都不用动。

显隐：不跟 Swup 纠缠，交给 CSS#

Firefly 的壁纸区在 Swup 容器外面，切页不重渲染。这意味着装饰层不能依赖”重新渲染时判断是不是首页”，得自己处理显隐。

我最后用的方案是纯 CSS 门控，和主题里滚动指示器的思路一致：

1
.home-wallpaper-decor {
2
  opacity: 0;
3
  visibility: hidden;
4
  /* ... */
5
}
6
html[data-wallpaper-mode="banner"] body.is-home .home-wallpaper-decor,
7
html[data-wallpaper-mode="fullscreen"] body.is-home .home-wallpaper-decor {
8
  opacity: 1;
9
  visibility: visible;
10
}

body.is-home 是服务端渲染 + Swup 切页时都会维护的类，data-wallpaper-mode 跟着壁纸模式走。这样切去文章页装饰层自动淡出，回到首页自动出现，一行 JS 都不用写。

入场动画最初是等卡片图片全部加载完再加 is-ready 触发，动画播完用 animationend 事件打上 is-motion-settled 标记固化终态。另外加了个 MutationObserver 盯着 body 的 class，每次从别的页面回首页时重播一遍入场动画。

拖拽的实现#

拖拽用 Pointer Events，鼠标和触屏一套代码。指针按下时记录贴纸相对壁纸容器的坐标，移动时换算成 left/top 并夹在壁纸范围内（Math.max(0, Math.min(容器宽 - 贴纸宽, ...))），配合 setPointerCapture 保证拖出元素外也不丢事件。移动端额外禁掉长按弹菜单的 contextmenu 和 iOS 的 touch-callout。

头像小贴纸的位移写 CSS 变量而不是 style.transform，这是踩坑 4 的教训——fullscreen 模式下主题有 transform: scale(1.05) !important，内联 transform 打不过它。

刷新后贴纸回到初始位置是故意的：不做 localStorage 记忆，访客拖乱之后下次进来还是整齐的。

移动端的自适应#

手机端和桌面端是同一套结构，靠脚本换算：解析每个贴纸初始配置里的 top/bottom/left 识别它属于左列、右列还是中间排，然后按卡片实际边界重排——顶部两张贴卡片上方两侧，底部五个 bottom 锚定在卡片下方，中间三个在左右两列之间等宽槽位居中。布局时机挂 load + setTimeout + 防抖 resize 兜底（后台标签页里 rAF 不触发，这个坑下面细说）。

坑 1：默认横幅文字阴魂不散#

装饰卡片上线后，“World and Life” 那套默认横幅文字还叠在卡片上。我明明在服务端把 showHomeText 关了，HTML 里也确实带着 hidden 类——但页面跑起来之后它又出现了。

翻主题源码才发现有个 syncBannerHomeTextVisibility()，会在运行时按”是否首页 + 壁纸模式”重新计算并把 hidden 类摘掉。它不认识我的卡片，只知道”首页就该显示横幅文字”。

不想去改主题的工具函数，最后用同一条件的 CSS 规则直接压死：

1
html[data-wallpaper-mode="banner"] body.is-home .banner-home-text-overlay {
2
  display: none !important;
3
}

这段 CSS 在我的组件里，组件不渲染时它也不存在，卡片关掉就一切恢复原状。

坑 2：看不见的卡片盒模型挡住了点击#

调试时发现分类栏的”归档”按钮点不动，Playwright 报错说元素被 article.home-wallpaper-card 盖住了。卡片是透明的，但盒模型是实打实的，社交标签下方还伸出去一截。

解法是把整个卡片设成 pointer-events: none，再只给真正需要交互的子元素恢复：

1
.home-wallpaper-card { pointer-events: none; }
2
.home-wallpaper-card__nav a,
3
.home-wallpaper-card__social-link,
4
.home-wallpaper-card__avatar-sticker {
5
  pointer-events: auto;
6
}

坑 3：切到 fullscreen 模式，贴纸三连崩#

把壁纸模式切成 fullscreen 之后怪事来了：贴纸变大了一圈、下半截被裁掉、滚动一下还糊成一团。

查出来是主题在 fullscreen 模式下有针对壁纸容器内所有 img 的规则，一共三条变体，其中最高的一条长这样：

1
html[data-wallpaper-mode="fullscreen"][data-fullscreen-layout="classic"] #wallpaper-wrapper img {
2
  width: 100% !important;
3
  height: 100% !important;
4
  object-fit: cover !important;
5
  filter: blur(var(--fullscreen-blur)) !important;
6
  transform: scale(1.05) !important;
7
}

它的本意是让壁纸图铺满全屏、滚动时渐变模糊，但贴纸图也是 img，全被扫进去了：cover 负责裁切，scale(1.05) 负责放大，blur 负责糊脸，三个症状一次凑齐。

修法是在我自己的组件里加更高特异性的豁免规则。主题那条是 (1,2,2)，我借自己容器的类提到 (1,3,2)：

1
html[data-wallpaper-mode="fullscreen"] #wallpaper-wrapper .home-wallpaper-decor .home-wallpaper-sticker img {
2
  width: 100% !important;
3
  height: auto !important;
4
  object-fit: contain !important;
5
  filter: none !important;
6
  transform: none !important;
7
}

坑 4：!important 大战之下，拖拽失效了#

修上面这个的时候又埋了个雷：transform: none !important 把头像小贴纸的拖拽也废了——JS 拖拽写的是内联 style.transform，在内联样式里 !important 之外，任何样式表的 !important 都能把它按在地上摩擦。

解法是拖拽位移不走 style.transform，改写 CSS 变量：

1
.home-wallpaper-card__avatar-sticker {
2
  transform: translate(var(--avatar-sticker-tx, 0px), var(--avatar-sticker-ty, 0px));
3
}

1
// fullscreen 下也照样能拖
2
sticker.style.setProperty("--avatar-sticker-tx", `${translateX}px`);
3
sticker.style.setProperty("--avatar-sticker-ty", `${translateY}px`);

变量赋值是内联的，规则里带 !important 的 transform 引用的还是这份值，两边不打架。

坑 5：移动端随机投放，是我自己想当然#

一开始照搬参考站的移动端方案：只显示 4 张 mobile: true 的贴纸，随机投放到四块写死的百分比区域。结果上线一看不对劲——区域是死的，卡片却是活的，窄屏下卡片占掉九成宽，两块”侧边区域”直接压在卡片上，一张贴纸骑在社交标签上，另外三张干脆没显示。

想明白了就把”随机投放”整个删掉：移动端显示全部贴纸，布局和桌面端同一套结构，坐标由脚本按卡片实际边界换算——顶部两张贴在卡片上方，底部五个 bottom 锚定在卡片下方，中间三个在左右两列之间等分槽位。这样不管屏幕多窄都自适应。

坑 6：布局代码写完了，后台标签页里根本不跑#

自适应布局写完，我自己截图验证，发现贴纸时对时不对，纯属玄学。排查半天是两个坑叠一起：

1. 布局被包在 requestAnimationFrame 里——后台标签页的 rAF 是不触发的，页面在后台加载时布局永远不执行
2. 依赖 matchMedia 的 change 事件切换布局——部分环境（视口仿真等）这个事件压根不派发

解法：布局改同步执行（读 getBoundingClientRect 本身就会强制布局，不需要 rAF），再补 load 事件、setTimeout 校准和防抖 resize 监听兜底。顺手把贴纸坐标的解析从正则换成了临时元素 + cssText，让浏览器自己拆 inset 简写——之前那个正则压根没算上百分号，一直匹配失败，全靠默认值兜底。

坑 7：贴纸素材太大了#

做完才反应过来，贴纸原图全是 1086×1448 的高清图，加起来 1.6MB，而它们实际只显示一百来像素宽——下载量是显示需求的十倍。用 ffmpeg 压到 192px 宽之后总共 126.8 KB，肉眼看不出差别：

1
cd public/images/home-stickers
2
for f in *.webp; do
3
  ffmpeg -y -loglevel error -i "$f" -vf "scale=192:-1" "tmp/$f"
4
done

八张图现在的实际尺寸和体积：

贴纸显示宽度是配置里的 width 乘上组件顶部的 STICKER_SCALE = 1.25，算下来在 98140px 之间。192px 的源图对这个显示尺寸是 1.42 倍，正好覆盖高清屏，再大就是纯浪费。

贴纸换成自己的了#

原来那批是参考站的演示图，8 张都是常见动漫 Q 版角色。后来换成了自己挑的一套，还是 8 张，布局位置一个没动：

换素材只动了 homeCardConfig.ts 里的 src 和少量 width，组件一行没改——这算是当初把内容全配置化的回报。压缩尺寸也顺便从 360px 收到了 192px，8 张图合计 126.8 KB（原本 330KB，再早是 1.6MB）。

入场动画拆成了两段#

这是被一组性能数据逼出来的改动。我跑了几轮 Lighthouse 测移动端，一直有个数字看不懂：最大元素（LCP）要 4 秒多才被浏览器认定”画好了”，而且查不到是哪张图拖的。

后来把 Lighthouse 的底层 trace 导出来（145MB）流式解析，才发现 LCP 元素根本不是壁纸、也不是卡片，是卡片里那行标题文字：

1
@ 2614 ms  type=text  size=15194  nodeName=SPAN class='home-wallpaper-card__motion-text'

顺着查到两个叠加的原因，都在这套入场动画里：

1. 标题的入场关键帧起点是全透明。它借用了通用的 home-wallpaper-content-enter，0% 是 opacity: 0；而动画用了 animation-fill-mode: both，意味着动画开始前就套用 0% 关键帧——于是它在 0.36 秒的延迟期间一直是全透明的，Chrome 不把 opacity: 0 的元素算作内容绘制，LCP 自然被推迟。
2. is-ready 要等图片。前面写的那句”等卡片图片加载完再加 is-ready”，把标题的入场也一起绑在了图片下载上。

改法是两刀：

• 给标题单独一版关键帧，起点直接 opacity: 1，只保留从下往上滑 12px 的位移；延迟从 0.36s 收到 0.08s。视觉上还是”滑上来”，但第一帧就算画好了。
• 入场逻辑拆两段：文字动画不再等图，两帧之后直接放行；图片单独走一条 is-media-ready 通道，只控制自己 0.24 秒的淡入。

1
@keyframes home-wallpaper-title-enter {
2
  0% { opacity: 1; transform: translateY(12px); }
3
  to { opacity: 1; transform: translateY(0); }
4
}
5
.home-wallpaper-decor.is-ready .home-wallpaper-card h1 {
6
  animation-name: home-wallpaper-title-enter;
7
  animation-delay: 0.08s;
8
}

拆图片通道时留了个安全垫：图片的隐藏规则写成 .is-ready:not(.is-media-ready)，只有 JS 确实接管、入场已启动时才隐藏它。这样脚本失效、或者访客开了”减弱动态效果”，图片都是直接可见的，不会永久空白一块。

顺手关掉了 Swup 的视口预取#

同一次体检里还挖出一笔大流量：Swup 的预取插件默认会把导航里露出来的链接全部提前下载。首页第一屏正好有 7 个链接满足条件（卡片导航 5 个 + RSS / 打赏），移动端一次抓回 483KB 页面 HTML，占总流量 34%。

改法是把它还原成上游那行 preload: true。这行配置的完整语义是”hover 预取开、视口预取关”，跟我想要的 visible: false 运行时完全等价，但和上游字节一致，以后合并上游连 diff 都不会产生——这是这次所有优化里唯一一条能减少合并负担的改动。

效果（部署后实测）：

桌面端分数没变（都是 89），但传输量从 2177 KiB 掉到 1142 KiB。桌面模拟带宽高，那 1MB 预取本来就不在关键路径上——所以桌面的收获是省流量，不是提分，这点得说清楚。

所有这些改动依然遵守着”不碰主题源码”的规矩：新增的关键帧、通道类名、门控规则全在 HomeWallpaperDecor.astro 里，这个文件上游根本没有，改它零冲突。astro.config.mjs 那行还反倒更接近上游了。

还没解决的#

说个不太好看的：移动端那 2 秒的白屏直到现在也没完全解释清楚。trace 里能看到渲染阻塞的 CSS 在 612ms 就全部就绪了，但 FCP 还是拖到 2655ms——中间这段空窗目前只能怀疑是字体或主题运行时脚本，没定位到确切的元凶。

所以性能这块还没收工，下次再测。