流萤看板娘 · 网页部署与油猴脚本

Features

不只是摆在角落里的模型

轻量接入、自然交互，并尽量避免影响正文浏览和页面性能。

动作与语音可重复触发

唱歌和“点燃星海”可以连续播放；再次触发时会立即停止旧动作，从头启动新的动作与音频。

十种随机互动

随机池包含唱歌、点燃星海与八种表情；桌面点击和移动端轻触未命中部位时都能触发，并避免连续抽到同一项。

消息框跟随真实发顶

根据当前帧可见 Drawable 计算发顶或猫耳最高点，保留安全距离，不再遮挡头发。

配件与控制面板

支持墨镜、猫耳独立开关；鼠标靠近模型时显示返回、随机、资料与隐藏按钮。

会留意你正在看的页面

自动读取页面标题；标题变化时也会重新问候，适合博客、文档站与单页应用。

标签页与链接感知

切回当前标签页时欢迎你回来；桌面悬停或移动端长按链接后，还会询问是否想去看看。

Use cases

适合放在哪里？

可直接嵌入自己维护的网页，也可通过油猴脚本在第三方网站中加载。

AList 文件站

在自定义头部或页脚中引入加载器，为资源页面增加陪伴感与互动入口。

个人主页与博客

作为固定在页面边缘的角色组件，配合首页、文章页和关于页面使用。

文档站与项目展示

通过欢迎语、按钮提示和 JavaScript API，引导访客了解项目功能。

油猴脚本与日常网页

通过 Tampermonkey 等脚本管理器挂载，并可按网站启用或停用。

Quick start

选择你的使用方式

自己维护的网站推荐直接部署；想让流萤出现在第三方网页，则使用油猴脚本。

适合 AList、博客、个人主页、文档站和其他允许插入 JavaScript 的页面。

上传整个目录。 保留 load/、model/、assets/、CSS 与 JS 的相对路径。
填写配置。 根据页面布局设置左右位置、桌面端和触摸端尺寸。
通过 HTTP(S) 访问。 不建议用 file:// 直接打开，浏览器可能限制音频与模型资源。

HTML 接入示例

<script>
window.FireflyLive2DConfig = {
  side: "left",
  width: 420,
  height: 420,
  scale: 0.94,
  offsetX: -20,
  offsetY: 12,
  allowTouch: true,         // 独立开启触摸屏移动端
  touchWidth: 260,
  touchHeight: 220,
  touchScale: 0.90,
  touchOffsetX: -12,
  touchOffsetY: 8,
  dialogGap: 1,
  pageTitleMessage: true,
  returnMessage: "欢迎回来~",
  linkHoverMessage: true,
  linkHoverDelay: 1400,
  linkLongPressDelay: 650,  // 纯触摸设备长按链接提示
  idleMessageDelay: 90000,
  homeUrl: "/",
  profileUrl: "https://baike.baidu.com/item/流萤/63849747",
  minWidth: 1025,
  debug: false
};
</script>
<script src="https://你的域名/firefly-loader.js" defer></script>

部署提示： 推荐使用绝对 URL 引入加载器；资源跨域时，请为模型、纹理、动作与音频配置正确的 CORS 响应头。

适合 Tampermonkey、Violentmonkey 等用户脚本管理器。脚本默认全站启用，可通过菜单对当前网站停用；运行时资源会在 jsDelivr 与自建源之间自动容灾。

安装用户脚本管理器。 Chrome、Edge、Firefox 等浏览器均可使用 Tampermonkey 或兼容扩展。
打开脚本安装页。 点击下方按钮，脚本管理器会识别 .user.js 并展示权限与安装确认。
按需修改配置。 可编辑 USER_CONFIG、黑白名单模式、桌面尺寸和触摸端参数。

安装油猴脚本查看脚本说明

油猴脚本关键配置

// 运行时资源：主源失败后自动尝试备用源
const RESOURCE_SOURCES = [
  {
    name: "jsDelivr",
    base: "https://cdn.jsdelivr.net/gh/Iskongkongyo/Firefly-live2d@v6.5.0/",
    timeout: 9000,
    binaryTimeout: 12000
  },
  {
    name: "自建源",
    base: "https://live2d.202132.xyz/",
    timeout: 15000,
    binaryTimeout: 25000
  }
];

// 触摸端默认开启；主源网络故障后熔断 5 分钟
const RESOURCE_SOURCE_COOLDOWN = 5 * 60 * 1000;
const USER_CONFIG = {
  side: "left",
  width: 420,
  height: 360,
  allowTouch: true,
  touchWidth: 260,
  touchHeight: 220,
  touchScale: 0.90,
  linkLongPressDelay: 650,
  minWidth: 1025
};

// 新增域名时同步添加 @connect；四行 @require 不支持脚本内自动回退

容灾说明： 模型、纹理、动作、表情、物理、音频和图标会按 jsDelivr → 自建源 自动切换，并在网络型故障后短暂熔断。四个 @require 在主脚本前加载，无法由 JavaScript 自动回退；必要时请直接改成自建源地址。脚本不会使用 Raw GitHub。

Configuration

参数说明

网页加载器未填写的字段会使用内置默认值；油猴脚本可在 USER_CONFIG 中填写同名参数。示例页将高度覆盖为 420px。

参数	默认值	说明
`baseUrl`	加载器所在目录	模型、依赖、样式和图标的资源基准路径。
`model`	`model/Firefly.model3.json`	Live2D 模型配置文件路径。
`core`	`load/live2dcubismcore.min.js`	Live2D Cubism Core 路径。
`pixi`	`load/pixi.min.js`	PixiJS 路径。
`live2d`	`load/cubism4.min.js`	pixi-live2d-display Cubism 4 构建路径。
`css`	`firefly.css`	组件样式文件路径。
`icon`	`assets/firefly-icon.jpg`	隐藏后用于恢复显示的按钮图标。
`side`	`"left"`	固定位置，可填写 `left` 或 `right`。
`width`	`420`	组件画布宽度，单位为 px。
`height`	`620`	组件画布高度，单位为 px；示例页面使用 420。
`scale`	`0.94`	模型在画布中的缩放倍率。
`offsetX`	`-20`	模型水平偏移，正值向右。
`offsetY`	`12`	模型垂直偏移，正值向下。
`zIndex`	`52`	组件与恢复按钮的层级。
`minWidth`	`1025`	仅控制非触摸桌面端的最小加载宽度，不再用于开启移动端。
`allowTouch`	`false`	是否允许在主指针为粗指针的触摸设备加载模型。
`touchWidth`	`260`	触摸模式画布宽度；超过可视视口时自动收缩。
`touchHeight`	`220`	触摸模式画布高度；超过可视视口时自动收缩。
`touchScale`	`0.9`	触摸模式下模型的独立缩放倍率。
`touchOffsetX`	`-12`	触摸模式水平偏移。
`touchOffsetY`	`8`	触摸模式垂直偏移。
`touchControlsHideDelay`	`3200`	触摸模型后控制按钮继续显示的时间。
`storageKey`	`alist-firefly-live2d-hidden`	网页部署使用 localStorage；油猴版使用 GM 存储，并默认按域名分别保存隐藏状态。
`welcome`	`开拓者，我回来啦~`	首次加载完成后显示的欢迎语。
`pageTitleMessage`	`true`	是否读取页面标题并显示“又在看 xxx 呀~”；标题变化时也会触发。
`pageTitleTemplate`	`又在看 {title} 呀~`	标题消息模板，`{title}` 会被替换为当前标题。
`pageTitleMessageDelay`	`3400`	首次标题问候延迟，避免覆盖欢迎语。
`pageTitleChangeDelay`	`700`	页面标题发生变化后的提示延迟。
`titleMaxLength`	`28`	页面标题在消息框中的最大字符数。
`returnMessage`	`欢迎回来~`	从其他标签页切回当前页面时显示；设为空字符串可关闭。
`returnMessageMinHidden`	`1000`	标签页至少隐藏多久才触发欢迎消息，单位毫秒。
`linkHoverMessage`	`true`	是否启用桌面悬停、键盘聚焦与纯触摸设备长按链接提示。
`linkHoverTemplate`	`想去看看{label}吗？`	链接消息模板；`{label}` 来自文字、aria-label、title 或 URL。
`linkHoverDelay`	`1400`	桌面端链接悬停多久后提示，单位毫秒。
`linkHoverDuration`	`2800`	链接悬停消息的显示时长。
`linkHoverCooldown`	`8000`	同一链接再次提示前的冷却时间。
`linkLabelMaxLength`	`22`	自动提取的链接名称最大字符数。
`linkLongPressDelay`	`650`	纯触摸设备长按链接多久后提示，单位毫秒。
`linkLongPressMoveTolerance`	`12`	长按期间允许的手指移动距离；超过后按滚动处理并取消。
`copyMessage`	`复制好啦，希望能帮到你~`	复制页面内容后的反馈；设为空字符串可关闭。
`copyMessageDuration`	`2300`	复制反馈消息显示时长。
`bottomMessage`	`已经看到页面底部啦，辛苦了~`	首次阅读接近页面底部时显示；设为空字符串可关闭。
`bottomMessageThreshold`	`0.92`	阅读进度达到该比例时视为接近页面底部。
`idleMessages`	3 条内置消息	长时间无操作时随机显示的陪伴语；设为 `[]` 可关闭。
`idleMessageDelay`	`90000`	首次空闲提示等待时间，单位毫秒。
`idleMessageInterval`	`120000`	后续空闲陪伴消息的间隔。
`fallbackClick`	`true`	点击或轻触未命中指定区域时，是否执行随机互动；桌面端与触摸端均生效。
`touchTapMoveTolerance`	`14`	触摸端判定轻触时允许的最大移动距离，单位像素；超过后视为滑动并取消互动。
`touchTapMaxDuration`	`600`	触摸端轻触的最长持续时间，单位毫秒；长按不会误触发随机动作。
`expressionDuration`	`4200`	八种表情保持时长，单位为毫秒。
`dialogGap`	`24`	消息框额外间距；实际安全距离约为 `6px + dialogGap`。
`buttonHintDuration`	`2600`	悬停控制按钮时提示消息的显示时长。
`controlsHideDelay`	`180`	鼠标离开模型与按钮区域后，控制栏延迟隐藏的时间。
`homeUrl`	`/`	🔙 按钮目标地址，可使用相对或绝对 URL。
`profileUrl`	流萤资料页	🔗 按钮打开的地址。
`profileHint`	流萤自我介绍	鼠标移入 🔗 按钮时显示的提示内容。
`debug`	`false`	开启后在控制台输出调试信息。

Interaction

互动与脚本控制

模型加载完成后，可通过 window.FireflyLive2D 在页面脚本中主动控制流萤。

模型点击区域

蛋糕唱歌
左侧后发点燃星海
刘海切换墨镜
右侧后发切换猫耳
其他区域随机动作 / 表情

常用 JavaScript API

show() / hide()显示或隐藏
say(text)显示消息
randomAction()随机互动
toggleSunglasses()切换墨镜
toggleCatEars()切换猫耳

JavaScript 调用示例

// 请在模型加载完成后调用
window.FireflyLive2D.say("欢迎回来，开拓者！", 3000);
window.FireflyLive2D.randomAction();
window.FireflyLive2D.toggleCatEars();

Credits

致谢与使用说明

感谢上游项目、开源库与模型作者。请尊重相关素材和项目的授权要求。

特别致谢

感谢 Scighost/Firefly 项目提供桌面端实现与相关资源参考；同时感谢 PixiJS、pixi-live2d-display 与 Live2D Cubism 生态。

非商用提醒

本适配包适合个人学习、技术研究与非商业展示。模型及相关素材版权归各自权利方所有，公开部署前请确认并遵守上游授权与素材使用规则。

让流萤陪你，停留在每一个页面。

不只是摆在角落里的模型

动作与语音可重复触发

十种随机互动

消息框跟随真实发顶

配件与控制面板

会留意你正在看的页面

标签页与链接感知

适合放在哪里？

AList 文件站

个人主页与博客

文档站与项目展示

油猴脚本与日常网页

选择你的使用方式

参数说明

互动与脚本控制

模型点击区域

常用 JavaScript API

致谢与使用说明

特别致谢

非商用提醒

让流萤陪你，
停留在每一个页面。