起因#

站里早有一篇 Live2D 看板娘的调研，当时的觉得太重，没必要复刻。巧的是，最近在 blog.pljzy.top 看到「桌面宠物」时，第一反应是——这不还是看板娘吗？看完才发现不是一回事，它走的是另一条完全不同的技术路线。

结论很清楚：表现力换轻量。雪碧图这条路的取舍很划算——没有 WebGL、没有模型解析、资源就一张图，而换成角色只要丢个目录进去。

三道坎里的「模型体积」和「Swup 重复初始化」，前者被压到 2.2MB，后者是本文的重点之一。于是决定：走这条路，角色选流萤——本站是 fuwari / Firefly 系，大小样式正合我意，话不多说，立刻开干。

一、资源三件套#

方案来自 ZyPLJ/WebCodexPet，MIT 许可（已把许可副本归到 public/lib/LICENSE-codex-pet.txt）。宠物按目录分，仓库里有流萤、芙芙、甘雨、财神派蒙四个，挑来拣去看中了流萤：

雪碧图规格是 1536×1872，8 列 × 9 行，每格 192×208。九行对应九种状态：

pet.json 就是描述这张表的说明书：

1
{
2
  "pet_id": "firefly",
3
  "display_name": "流萤",
4
  "atlas": { "columns": 8, "rows": 9, "cell_width": 192, "cell_height": 208,
5
             "width": 1536, "height": 1872 },
6
  "rows": [
7
    { "state": "idle", "row": 0, "frames": 6, "purpose": "calm resting, breathing, and blinking loop" },
8
    { "state": "running-right", "row": 1, "frames": 8, "purpose": "rightward drag movement loop" }
9
  ]
10
}

SDK 侧的逻辑直白到一句话能讲完：requestAnimationFrame 推进帧号，然后按行列裁格画到 canvas 上——

1
ctx.drawImage(spritesheet, col * 192, row * 208, 192, 208, 0, 0, 192, 208);

为什么是自托管而不是引 CDN：跨域雪碧图必须由对方开 CORS，否则 canvas 会被标记为「脏」，一旦后续有读像素的操作就会抛安全异常。自托管没这个问题，代价是 2.3MB 进仓库、走 CF 分发——这个代价我认为值得，理由在最后一节。

二、挂载：三个先想清楚的决策#

配置收在 src/config.ts 的 petConfig（类型在 src/types/config.ts），挂载代码在 src/layouts/Layout.astro 末尾。有三件事必须在写第一行代码前定下来。

1
{petConfig.enable && <div id="site-pet-host" aria-hidden="true"></div>}

1
function mountPet() {
2
  if (!cfg.enable) return;
3
  if ((window as any).__sitePetBooted) return;
4
  (window as any).__sitePetBooted = true;
5
  // ...
6
}

1
function schedulePet() {
2
  if (!cfg.enable) return;
3
  if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
4
  if (cfg.hideOnMobile && narrow.matches) return;
5
  const ric = (window as any).requestIdleCallback;
6
  if (typeof ric === "function") ric(mountPet, { timeout: 2500 });
7
  else setTimeout(mountPet, 1200);
8
}
9

10
if (document.readyState === "complete") schedulePet();
11
else window.addEventListener("load", schedulePet, { once: true });

1
const s = document.createElement("script");
2
s.src = `${BASE}lib/codex-pet.js`;
3
s.async = true;
4
s.onload = mount;
5
document.head.appendChild(s);

三、上游没管的六件事#

SDK 的开箱默认值是「demo 友好」，直接照抄到博客上会出事。以下六处是我改的。

第 1 条最要紧。本站的浮层层级是有约定的：

SDK 默认那个 2147483000 是个「压过全世界」的值——宠物会飘在目录抽屉上面，点抽屉时被它挡住。配置里我把层级作为一个显式参数暴露出来，注释就写着本站在用的这几个值：

1
zIndex: 40, // 低于悬浮工具栏(50)与目录抽屉(60)

第 2 条是因为本站右下角已经有悬浮工具栏（回到顶部、主题切换那排按钮），宠物默认也在右下，会挤成一团。左下角是空的，放它正合适。

第 5 条如果漏了，你会收到用户关于「风扇转得厉害」的反馈——后台标签页里 requestAnimationFrame 是被节流的，但节流不等于停止，动画仍在跑：

1
document.addEventListener("visibilitychange", () => {
2
  const p = (window as any).sitePet;
3
  if (!p) return;
4
  if (document.hidden) p.pause();
5
  else p.resume();
6
});

第 6 条小但体面。SDK 加载失败时会往页面里插一个红色错误提示框，那是给开发者调试用的：

1
onError(err: any, inst: any) {
2
  console.warn("[sitePet]", err && err.message);
3
  try {
4
    inst?.shadow?.querySelector(".cp-error")?.remove();
5
  } catch { /* ignore */ }
6
},

另外还有第 7 处，不算「改」算「修」：上游那个 pet.json 带 UTF-8 BOM。原文章的踩坑记录里也提过这一点。我在落地前去掉了 BOM，否则 JSON.parse 在某些解析路径上会直接抛错。

四、换角色 / 关掉#

• 换角色：宠物包整个目录丢进 public/pets/<id>/，改 petConfig.id 即可。上游还有芙芙（fufu-sticker）、甘雨（ganyu-pet-v2）、财神派蒙（rich-paimon）可选，但资源要自己下载自托管。
• 临时关掉：petConfig.enable = false，宿主容器和脚本都不会输出。
• 调大小 / 速度：scale（0.5 → 96×104 px）、speed（毫秒每帧，当前 120）。
• 换位置：position 支持四个角，margin 是边距。

配置全文如下：

1
export const petConfig: PetConfig = {
2
  enable: true,
3
  id: "firefly", // 流萤；可选 fufu-sticker / ganyu-pet-v2 / rich-paimon（须自备资源）
4
  spritesheet: "", // 留空 = /pets/<id>/spritesheet.webp
5
  scale: 0.5, // 0.5 → 96×104 px
6
  speed: 120, // 毫秒/帧
7
  position: "bottom-left", // 左下角（右下角已被悬浮工具栏占用）
8
  margin: 18,
9
  state: "idle",
10
  zIndex: 40, // 低于悬浮工具栏(50)与目录抽屉(60)
11
  draggable: true,
12
  clickCycle: true,
13
  hideOnMobile: true,
14
};

小结#

回头看，这件事真正花时间的不是「把宠物挂上去」——那部分是十来行配置和一次 mount 调用。花时间的是那三道老坎：

1. 体积：从 Live2D 的几十 MB 换成一张 2.2MB 的图，从「不敢上」变成「可以上」；
2. Swup：把宿主挂在容器之外 + 单例守卫，切页时宠物纹丝不动、也不叠加；
3. 抢位：主动改掉那个「压过全世界」的层级，让宠物老实待在正文之上、工具栏之下。