[Github] page-mascot – 让网页角色跟随鼠标的开源 React 吉祥物组件

page-mascot 是一个开源 React 网页吉祥物组件：角色会朝鼠标所在方向转头，点击后眨眼、冒爱心或露出开心表情。它适合给个人主页、作品集和轻松风格的产品页面增加一点互动。接入现成角色只需要组件和两张精灵图；想做自己的形象，则可以使用项目附带的 Agent Skill 生成并校准素材。

视线如何跟着鼠标走

page-mascot 没有实时生成动画，也不需要把角色做成三维模型。每个角色由两张 3×3 精灵图组成：一张保存九个头部朝向，另一张保存九种表情。组件按鼠标相对角色的角度选择对应格子，因此看起来像角色一直在关注光标。

同一只狐狸的方向图与表情图，各由 3×3 格组成。来源：Kamran Ahmed / page-mascot 官方仓库（MIT）。

光标靠近角色时，视线会回到中间，源码还对方向切换做了缓冲，避免鼠标停在分界线上时来回跳动。点击时会短暂切到表情图，并配合挤压回弹；当前实现会先眨眼，再显示爱心、闪光或开心反馈，短时间连续点击还会触发晕眩表情。图集中有九种表情，不代表每次点击都随机播放全部九种。

这套实现的重点是素材对齐。如果两个格子里的头部尺寸、位置或身体基准不一致，切图时角色就会跳动。它更适合保持姿态稳定的小头像或吉祥物，而不是需要连续走路、复杂骨骼运动的动画角色。

把狐狸放进 React 页面

仓库当前的 package.json 声明 React 18 及以上、Node.js 20 及以上。它是供前端项目使用的组件，并非安装后就能自动出现在任意网站上的浏览器扩展或 WordPress 插件。下面按 README 的狐狸示例整理接入路径。

1. 打开官方演示页 https://koboyo.com/page-mascot，选择狐狸角色，下载它的方向图与表情图。
2. 在支持 public 静态资源目录的 React 项目中，将两个文件放到 public/mascots，分别命名为 fox-directions.webp 和 fox-reactions.webp。
3. 在项目目录安装组件，然后把下面的 JSX 放进需要显示角色的 React 页面。

npm i page-mascot

import { Mascot } from 'page-mascot'

export default function ProfileMascot() {
  return (
    <Mascot
      directions="/mascots/fox-directions.webp"
      reactions="/mascots/fox-reactions.webp"
      size={160}
      label="fox mascot"
    />
  )
}

directions 与 reactions 接收浏览器可以访问的图片地址，不是电脑上的文件路径。使用 public 目录时，URL 通常不包含 public 这一层；已有图片导入流程的项目，也可以传入导入后得到的地址。示例将显示尺寸设为 160 像素，组件默认值是 140；label 用于辅助技术识别，className 可供页面布局使用。

启动项目已有的开发预览后，应能看到狐狸，移动鼠标时改变朝向，点击时短暂切换表情。若角色空白，先在浏览器直接打开两条图片 URL，确认没有 404；若能显示却动作错乱，则核对两张图是否放反，以及是否仍保持官方九宫格布局。这段代码是依据官方用法整理的接入示例，未在本文中做项目级运行测试。

生成自己的角色

已有角色适合先验证页面效果；需要品牌吉祥物或个人化身时，再使用仓库提供的 page-mascot Skill。官方给出的安装命令如下，其中 --global 表示安装到全局技能位置。

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

安装后，可以向支持该技能的 Agent 提出具体要求，例如下面这句生成 riso 风格的 Q 版狐狸：

/page-mascot a chibi fox, in the riso style

官方列出的六种风格是 colour、ink、sketch、riso、paper 和 pixel，分别对应彩色、墨线、素描、孔版印刷质感、纸艺和像素表达。它们改变的是角色画法，接入时仍然使用方向图与表情图这两个参数。

Skill 的工作不止画一张头像：它要制作九个朝向和九种表情，整理成两张对齐的图集，检查切换时角色是否跳动，再放入页面。生成环节需要可用的图片工具；项目 README 为不同 Agent 说明了内置图片工具或图片 API 路径，也允许取出仓库里的提示词，在其他图像生成界面制作素材。组件采用 MIT 许可，不等于外部图片生成服务免费。

如果只是更换配色或画风，尽量保持头部比例、眼睛位置和角色中心一致。先确认默认朝向与点击表情能稳定切换，再继续制作整套角色，比把十八张独立插画直接拼起来更容易得到自然的反馈。

触屏与上线取舍

组件只在同时支持悬停和精细指针的环境里开启视线追踪，纯触屏设备不会照搬桌面鼠标的效果。它还读取 prefers-reduced-motion：用户选择减少动态效果时，会跳过点击后的挤压回弹，但表情状态仍会切换。因此，减少动态效果不等于把所有反馈都关闭。

它很适合作品集里的小互动，却不应挡住导航、表单或购买按钮。上线前需要检查小屏幕占位、键盘焦点、图片加载和页面原有样式；如果页面强调严肃阅读或高密度操作，把角色缩小并放在非核心区域通常更合适。项目使用两张图片完成交互，实际资源体积仍取决于所选素材，不能仅凭组件结构就断言不会影响性能。

截至 2026 年 9 月 18 日核对，仓库约有 698 Stars、64 Forks，创建于 9 月 14 日，最近推送为 9 月 15 日；仓库 package.json 标记为 0.1.0，尚未查询到 GitHub Release。它仍是很新的项目，可以先用在个人站或实验页面，不宜把短期关注度当成长周期维护保证。

源码与演示入口

项目采用 MIT 许可证，署名 Kamran Ahmed。使用、修改和分发代码时应保留相应版权与许可声明。想了解代码托管与仓库基本用法，可先查看站内的 GitHub 介绍。

• 项目仓库与 README：nilbuild/page-mascot
• 角色演示与素材下载：https://koboyo.com/page-mascot
• 自定义角色提示词：https://github.com/nilbuild/page-mascot/blob/main/skills/page-mascot/reference/prompts.md