Aezh'ir Rhery - null

新手向完全从0开始的L2D网页挂件教学

从0到网页上线：制作一整套Live2D网页挂件的新手流程

page icon
注意：此文由整个过程陪伴我的狗屁通老师chatGPT所写，我修改了其中部分内容，但整体都保留了，有什么问题可以找它负责。
主要针对会画图的人，想使用自己画的live2D看板娘挂件而写。 如果你想直接用现成的，可以看看live2d-widget。
本站猫猫的制作记录可以看这里。
live2D软件使用部分，需要自行学习如何制作，推荐一边看官方视频教程，一边自己动手做，遇到问题再问GPT，1-2天即可做出一只猫猫。
代码部分，不会的话就直接叫GPT帮忙生成即可。也可以在实际做完后让它生成一份学习笔记，可以顺便学一下。 不过就我的经验来说，有这个时间死磕代码，不如再多搓几只猫猫……如果你是程序员当我没说。（程序员不需要看这篇文章吧！）
这份笔记整理的是一条实际跑通的路线：
先用官方样例碗中小年糕（文件夹名：Wanko）跑通 Web SDK → 修改鼠标跟随与画布 → 接入 NotionNext / Danbouru → 再替换成自己的猫猫模型 → 最后部署到远程网页。
适合第一次做 Live2D 网页挂件的人参考。
本文以 Live2D Cubism 5.x + 官方 Web SDK 为主，不使用第三方 renderer。
PS：理论上使用任意样例都行，但需要注意版本兼容。

1. 整体思路

整个项目可以拆成 4 层：
  1. Live2D Editor
      • 负责制作模型本体
      • 参数
      • 物理
      • 动画
      • 导出 .model3.json / .moc3 / textures / motions / physics
  1. Cubism Web SDK Demo
      • 负责让模型在浏览器里运行
      • 鼠标跟随
      • WebGL 绘制
      • canvas
      • 模型加载
  1. 网页挂件入口
      • 负责把 Core 和 widget JS 加载进网页
      • 判断桌面 / 手机
      • 避免重复加载
  1. 最终网站
      • 例如 NotionNext / Danbouru
      • 负责实际展示
      • Vercel / 其他平台部署
可以把它理解成：

2. 准备工具

需要准备：
  • Live2D Cubism Editor 5.x
  • Cubism SDK for Web
  • Cubism Web Framework
  • Cubism Web Samples
  • Node.js
  • npm
  • Git
  • GitHub Desktop
  • VS Code
  • 一个可部署的网站项目
Windows 下推荐：
如果 PowerShell 因执行策略阻止 npm，可以改用 CMD。

3. 先不要急着上自己的模型

新手最稳妥的办法是：
先用官方 Wanko 模型把网页端整个流程跑通。
这样可以把问题分开：
  • 如果 Wanko 都跑不起来 → Web SDK / 路径 / build 有问题
  • 如果 Wanko 正常，自己的模型不正常 → 模型导出或参数问题
这一步非常重要。

4. 跑通官方 Cubism Web Demo

进入官方 Demo 目录，例如：
Windows CMD 跨盘符时：
安装：
编译：
本地运行：
确认官方 Demo 页面可以打开。

5. 只加载一个模型

为了调试简单，建议先只保留 Wanko。
在：
里把模型列表改成只加载：
这样不会同时加载 Haru、Hiyori 等其他样例。

6. 解决 Wanko 鼠标跟随问题

一个容易踩到的坑：
官方新 Samples 默认使用新版参数名，例如：
但 Wanko 是旧参数命名：
所以如果直接跑新版 Demo，Wanko 可能显示正常，但头不会跟随鼠标。
在：
的 setupLook() 中改成 Wanko 的 legacy 参数：
改完后 Wanko 的头和身体就可以跟随。

7. 让模型跟随整个网页鼠标，而不是只在 canvas 内

官方 Demo 通常只在 canvas 捕获区域内响应。
作为网页挂件，希望：
鼠标移动到网页任何位置，角色都能看过去。
在：
中修改 onPointMoved()：
这一步的作用是：
这样即使挂件 canvas 很小，也能跟随整个页面鼠标。

8. 透明背景

网页挂件通常不需要 Demo 的背景色。
在：
将：
改成透明：
这样 canvas 背景就是透明的。

9. 删除 Demo 背景图和齿轮按钮

官方 Demo 默认有背景图、齿轮等 UI。
网页挂件一般不需要。
在：
把 initializeSprite() 简化成只创建 shader：
如果原代码里有：
相关 release 或点击逻辑，也需要相应移除或注释。

10. 把 canvas 做成真正的网页挂件

在：
创建 canvas 时设置样式。
例如：
这里几个关键点：

固定定位

这样页面滚动时挂件不会跟着内容移动。

左下角位置

负数完全可以，用来把 canvas 的空白区域推出屏幕。

不阻挡网页点击

这非常重要。
否则 Live2D canvas 会盖在网页按钮和链接上面。

11. 调整位置时不要每次都 build

为了快速找合适的位置，可以先在浏览器：
直接改 inline style：
浏览器会实时移动。
确认最终坐标后，再回到：
正式写入。
这样调试效率会高很多。

12. 让 Demo 支持动态 script 加载

官方 Demo 原本往往依赖：
如果以后把它作为动态 <script> 插入网页，页面可能早就 load 完了。
所以在：
改成：
这样：
  • 页面尚未加载完 → 等 load
  • 页面已经加载完 → 立即启动
这对“网页挂件 JS”非常关键。

13. 资源路径改成绝对路径

为了让模型在任意页面路由都能正常加载，推荐使用网站根路径。
在：
例如：
不要依赖相对路径：
否则进入：
时很容易 404。

14. 配置 Vite 输出固定文件名

默认 Vite build 会生成带 hash 的 JS。
网页挂件更适合固定：
在官方原本的：
里保留原配置，只修改 build 输出：
同时：
注意：
不要为了这一步新建一个极简 vite.config.ts 覆盖官方配置。
否则很容易把原 Demo 的 alias / publicDir 等配置丢掉。

15. Build 出最终 widget

修改完成后：
确认生成：
这个 JS 就是最终网页端运行核心。

16. 把运行资源复制到网站项目

例如网站使用：
最终结构可以是：
如果以后换成自己的模型：
即可。

17. 网站端加载方式

网站需要先加载 Cubism Core，再加载：
例如 React / Next.js 中可以写一个 loader component：

18. 手机端不要初始化

如果挂件只想在桌面显示：
最好不是“手机端隐藏 canvas”，而是“手机端根本不加载 Live2D”。
也就是在 loader 最前面：
这样手机端不会下载：
可以节省流量和性能。

19. 防止重复加载

Next.js / React route 切换、Strict Mode、Fast Refresh 都可能让组件重新 mount。
所以要加全局标记：
加载成功：
这样不会出现：

20. 本地调试顺序

建议每次修改都按这个顺序排查：

第一步：Demo 本身

确认官方 Demo 可以显示模型。

第二步：确认 build 文件存在

第三步：复制到网站

复制到：

第四步：直接访问 JS

浏览器打开：
确认不是 404。

第五步：直接访问模型

例如：

第六步：看首页

最后才看挂件是否显示。

21. 一个实际踩过的坑：build 后忘了复制 JS

很容易出现：
原因并不是 Live2D 挂了，而是：
没有复制回：
所以建议每次 build 后都检查：

22. Git / .gitignore

为了避免把整个 SDK 文档、source map 等都提交到仓库，可以只保留运行必要文件。
例如：
以后换成自己的模型，把：
改成自己的模型目录即可。

23. 部署远程网站

如果使用 Vercel：
部署后先检查：
这些都正常，再检查首页挂件。

24. 从 Wanko 替换成自己的模型

网页端跑通后，才开始替换模型是最省事的。
Cubism Editor 里主要需要准备：
  • 总之，先学会使用并制作live2D模型即可！

25. 自己的模型参数命名

如果想让新版 SDK 更方便，可以直接使用常见标准参数名：
这样 setupLook() 不需要像 Wanko 那样额外兼容 legacy ID。

26. 鼠标交互可以这样设计

这是目前本站使用的方案：

27. 动画建议

例如：

摇头

避免浏览器切动画时末尾被截断。

睡觉

可以拆成：
网页端逻辑再决定：

28. 物理建议

适合做物理的：
不适合完全靠物理控制的：
头部通常直接由参数控制，耳朵尾巴再跟随物理。

29. texture 尺寸

网页挂件没必要放超大纹理。
可以根据实际显示尺寸压缩。
例如：
具体取决于模型画布和细节。
原则：
网页上最终只显示 200～400px 左右，就没有必要上传原始超大 PSD / PNG。

30. 关于“防盗图”

只要 Live2D 在浏览器显示：
texture 数据最终一定会发送到用户浏览器。
所以不能真正做到：
能做的是提高提取门槛：
  • 发布缩小后的 texture
  • 不上传原始 PSD
  • 私有源码仓库
  • texture 打进 JS
  • 转 blob / binary
  • 隐性水印
  • 只公开网页运行尺寸
但这些都只是增加成本，不是绝对防止提取。
……随便吧你又不是把PSD原图放了上去！

31. 以后可以做成“一条 JS 地址即可使用”

最终可以把整个挂件包装成：
让朋友只需要引用一个入口 JS。
入口 JS 内部负责：
使用者不需要理解 Cubism SDK。
这个部分因为已经有很多人做了，加上这个阿尔猫猫是本站特供，我暂时没有考虑。 有人想用的话可以留言给我，我马上就做（？）

32. 可以继续加配置参数

例如未来可以设计成：
这样可以自己调整：

33. 最终推荐目录结构

34. 最重要的新手经验

如果只记住几件事，可以记这些：
  1. 先用官方样例模型跑通网页，再换自己的模型。
  1. 模型问题和网页问题要分开排查。
  1. 路径尽量用 /live2d/... 绝对路径。
  1. canvas 一定要 pointer-events: none。
  1. 手机端最好完全不初始化。
  1. Next.js 要防止重复加载。
  1. 每次 build 后确认 live2d-widget.js 已复制到网站。
  1. 不要一开始就魔改太多 SDK 文件，一次改一个变量。
  1. 位置调试先用 DevTools，不要每次重新 build。
  1. Web Live2D 的 texture 本质上一定会下发到浏览器。

35. 一句话版流程

36. 后续可继续扩展

在基础挂件稳定以后，可以继续做：
  • 自动眨眼
  • 呼吸待机
  • 点击播放动作
  • 点击循环 N 次
  • 长时间无操作进入睡眠
  • 鼠标移动唤醒
  • 多动作随机播放
  • 表情切换
  • 夜间模式
  • 用户自定义位置
  • 用户自定义缩放
  • 通用 model-widget.js
  • 跨域 CORS
  • 多网站复用
  • 单 JS 引用式分发
这时它就不再只是“网站里的一只 Live2D”，而是一套可以独立分享的网页挂件系统。
2026-10-72026-10-7
纸团
折腾
小技巧

没有找到文章