page-mascot：让你的网页拥有一只会"看"你的吉祥物

你有没有想过，当访客在你的个人网站或作品集页面上滑动鼠标时，角落里有一只小狐狸正悄悄地盯着光标走？当你戳它一下，它会害羞地眨眼、冒出一颗爱心，或者转出一圈星星？——这就是 page-mascot 正在做的事。

起源：给网页加点"生命感"

page-mascot 诞生于前端开发者 Kamran Ahmed（GitHub @nilbuild）之手。他的作品集网站 kamran.fyi 一直是他技术实力的展示窗口，但总觉得少了点什么——访客来了，页面是静态的，感受不到"被看见"。于是他花了点时间，把浏览器里最容易被忽略的鼠标移动事件，变成了一个能感知空间位置、会做出反应的动态角色。

这个创意在 Product Hunt 上线后迅速获得关注，随后在 GitHub 开源社区传播，目前已积累超过 800 颗星，成为了一个独立 npm 包，被数百个个人网站和创意项目所使用。

原理揭秘：精灵图 + 指针三角定位

从技术实现来看，page-mascot 的核心机制非常精巧——没有用到任何 AI 模型或复杂计算，纯粹是 CSS/React 组合拳。

每个角色由两张 3×3 精灵图（sprite sheet） 组成：

• 方向图（directions sheet）：九宫格，涵盖上、下、左、右、左上、左下、右上、右下、正中九个方位
• 表情图（reactions sheet）：同样是九宫格，包含眨眼、爱心、星星、惊讶、眨眼、害羞、困倦、晕眩、开心九种表情

角色的朝向由鼠标相对组件的角度决定，通过 Math.atan2(dy, dx) 计算弧度，再映射到 45° 一格的扇区。为了避免鼠标轻微晃动导致角色头部频繁抖动，代码里加入了 0.12 弧度的磁滞区间（hysteresis），只有当指针明显越过边界时才切换方向。

点击交互（Boop）则通过计时器队列驱动表情切换：先展示眨眼，再根据连续点击次数轮换"爱心→星星→开心"，连续快速点击四次以上角色会进入"晕眩"状态，需要等待 1.6 秒冷却。

page-mascot 仓库封面图

上手有多简单？

对于前端开发者，引入 page-mascot 的门槛极低：

import { Mascot } from 'page-mascot'

<Mascot
  directions="/mascots/fox-directions.webp"
  reactions="/mascots/fox-reactions.webp"
/>

你需要做的只是准备两张对齐好的精灵图（官方提供了超过 50 种预设角色，从宇航员到熊猫应有尽有），然后把路径传给组件即可。组件本身只依赖 React 18+，无需任何额外配置。

最有意思的玩法：AI 生成原创角色

page-mascot 还提供了一个 AI Agent 技能包，允许你用自然语言描述一个角色，然后让 AI 自动画出九方向 + 九表情的精灵图：

npx skills add nilbuild/page-mascot --skill page-mascot --global --yes

安装后对 AI Agent 说：/page-mascot a chibi otter with chocolate-brown fur，Agent 会调用 OpenAI 的图像生成 API，依次生成 18 张分格图片，排列检查对齐是否正确，最终输出一个可用的角色包。

这个功能的妙处在于：精灵图的一致性是 AI 生成最大的难题，page-mascot 通过"先画九方向，再画九表情，分格裁剪"的流水线，把这个难题转化成了顺序调用的简单操作。

局限与边界情况

作为一个纯前端的交互组件，page-mascot 的能力边界很清晰：

不支持的场景：

• 服务器端渲染（SSR）：组件依赖 window.matchMedia 等浏览器 API，Node.js 环境无法运行
• 非精细指针设备：手机/平板触摸场景下鼠标追踪会自动关闭（通过 hover: hover and pointer: fine 媒体查询检测）
• 无障碍（a11y）：组件以 <button role="img"> 渲染，label prop 传给 aria-label，但复杂精灵图对读屏软件仍不够友好

内置的优雅降级：

• prefers-reduced-motion 用户：点击后直接展示表情，跳过弹跳动画（squash & stretch）
• 移动端：组件静默隐藏，不影响布局

行业意义：小切口做出大文章

page-mascot 不是一个解决核心问题的工程库，它的价值在于降低了"给网页增加人情味"的门槛。在过去，给网站加一个动态吉祥物可能需要一周的动画设计和开发投入；现在，一个 npm install + 两张图片就能搞定。

这种"降低创意门槛"的工具哲学，与 Web Components、Low-code 的大趋势一脉相承——把复杂的技术封装成直觉的接口，让创意者专注于"想要什么"而不是"怎么实现"。

从增长曲线看，page-mascot 的 Star 增长相对平稳，没有爆发式增长，但也几乎没有衰减，说明它服务的是一个稳定的长尾需求：个人开发者、独立项目、小型作品集。这类用户群恰好是 GitHub 生态最活跃的贡献者，也是开源世界最忠实的参与者。