简介这套专门用于定制个人专属Live2D看板娘的资源包面向Web前端开发者和动效爱好者目的是帮助你使用JavaScript、CSS与HTML技术从零搭建一个可交互的二维动画看板娘完整覆盖模型调用、动作触发、交互响应与页面融合等主要流程。整个压缩包包含570个文件整体体积约为90.3MB核心文件类型包括218个动作脚本、143张贴图、52个配置数据以及11个模型数据文件同时还有音频、示例网页、交互脚本和说明文档类型多样便于按需查阅和调试。目前已有2726人学习下载适合直接在浏览器中运行体验。通过动手实践读者能深入理解二维动画技术原理掌握用脚本控制模型运动与响应点击学会用样式表处理看板娘布局和动画细节同时熟悉配置数据驱动模型参数的机制无论是用于个人网站装饰还是作为前端学习项目都能打造出独一无二的专属看板娘。1. 定制 live2D 看板娘不是从建模开始的是从“接一个现成模型”开始的一个下午的时间足够让网页右下角出现一个会眨眼、会跟着鼠标转头、点一下会有反应的 live2D 看板娘。这句话很多人不信因为第一反应是“我得先学会画立绘再用 Cubism 绑骨”。但真正落地过的人都知道最聪明的路线是先别碰建模把社区里现成的模型资源跑通整套渲染链路再把它换成自己的模型最后才谈得上定制。这篇笔记就顺着“先跑通、再替换、后定制”的顺序把运行时选型、文件结构、参数配置和翻车点完整过一遍适合想给个人博客、自用工具页或本地演示环境加一个角色又不想掉进 SDK 文档里的读者。2. 看板娘落地路线先选运行时再找模型别急着学建模做“能在页面上动的 live2D 角色”核心难点不在画图而在渲染运行时。画好的模型只是一堆资产必须有引擎去加载、解析、驱动参数这步才是决定你后面要不要加班到凌晨的关键。看板娘这个需求市面上的落地路线一共有三条下面按上手成本排个序。2.1 三条路线怎么选网页嵌入、桌面壳、原生 SDK第一条是网页嵌入直接用社区维护的 live2d-widget 这类浏览器封装。它把 Cubism Web 运行时、canvas 挂载、鼠标交互、台词气泡这些全都打包好了。绝大多数人的看板娘需求包括博客挂件、个人主页装饰、内部工具页彩蛋用这一条就够了。第二条是桌面端拿同一套网页包一层 Electron 或 Tauri适合想要开机自启、托盘图标、快捷键呼出的人。第三条是调 Cubism Native SDK 自己写渲染循环适合想把 live2D 集成进游戏、播放器这类自研产品里的代价是要啃 C API 和资源管理投入产出比很低普通人没必要碰。很多人搜过“碧蓝航线 live2d 播放器”这类工具其实那些播放器的本质就是拿同一个 Cubism 运行时把游戏里提取的模型资产渲染出来和网页里的看板娘完全同源。所以别被“播放器”三个字绕晕你能跑通网页版就等于拿到了同一套底层能力。对九成的人来说我的建议非常直接选第一条。理由有三点一是无需编译环境二是因为模型资产可以跨端复用以后想套桌面壳直接复用同一套页面三是社区方案遇到问题搜得到答案。Electron 壳适合你已经把网页版玩熟、还想更进一步的时候再考虑。2.2 模型资源去哪找三个来源和一个授权红线模型是另一个老大难。常见的来源就三个按推荐程度排来源特点授权风险Cubism 官网官方示例模型质量高、结构规范、适合练手个人使用无风险商用受限社区整合包搜 “live2d 下载免费” 或 live2d-master.zip 这类资源种类多、风格杂很多是爱好者复刻或练习看每个包内附授权说明多数仅限个人游戏提取/拆包资源质量最高绑定最细版权风险极高公开传播要谨慎“live2d下载免费”这个搜索词背后能找到的绝大多数是社区整合包。这类包的典型特征是一个 zip 解压后里面有 model 文件夹、贴图、json 配置文件偶尔附带一个 html 演示页。下载后第一件事不是解压看贴图而是先找包里的 README 或授权文件。没有授权文件的默认只能自己在本地玩不要往博客、公众号页面这类公开环境挂。这不是道德洁癖是因为很多游戏提取模型哪怕只是展示也会触发平台的版权审核。2.3 Cubism Editor 免费版够用吗绑定参数和你真正需要掌握的技能第二个常见问题是“我能不能自己做模型”。Cubism Editor 官方有免费版免费版提供完整绑骨功能只是项目和可输出参数有数量限制不能商用。做一只看板娘完全够用。如果只是给现有模型换个衣服颜色、加个眼镜、改个发型那其实连新建项目都不一定需要在 Photoshop 里改好贴图回到 Cubism 里重新导出一次就行不需要重新绑骨。真正需要从头过一遍的流程是这样的PS 分层画好立绘导入 Cubism 后把每个部件拆开、绑定网格变形器、设置眼睛和头部的角度参数、加上头发和裙子的物理摆动最后导出 .moc3 文件和配套贴图。整套流程走完一遍大概要一周但那是“做模型”的事和“定制看板娘”是两码事——定制看板娘现在就能开始。3. 跑通第一个本地看板娘live2d-widget 的最小工程先说结论最小的可运行工程只需要一个 html 文件、一个 live2d-widget 本体目录、一个模型文件夹。整个项目不超过 5MB如果模型贴图不大。下面按目录、代码、预览三步走。3.1 文件结构与最快的引入方式先把目录结构定下来。这是最常见的布局我自己的项目也一直这么放my-maid/ ├─ index.html ├─ model/ # 模型资源目录 │ └─ maid/ │ ├─ maid.model3.json # Cubism 3/4/5 模型配置 │ ├─ maid.moc3 # 模型数据 │ └─ textures/ # 贴图 └─ live2d-widget/ # widget 本体从 npm 或 GitHub 解压 └─ autoload.jslive2d-widget 本体是社区维护的浏览器封装通过 npm 装或者直接下载 zip 解压都行。把解压后的live2d-widget整个文件夹放进项目目录模型文件夹放进model目录然后写 index.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 title我的专属看板娘/title style body { margin: 0; min-height: 100vh; background: #f6f6f6; } /style /head body !-- 你自己的页面正文内容 -- script src./live2d-widget/autoload.js charsetutf-8/script /body /html这段代码背后发生了什么autoload.js会负责三件事在页面右下角自动插入一个 canvas读取默认路径./model/下的模型配置并且把点击、拖拽、台词气泡全部初始化好。也就是说上面三段代码就已经是完整的最小工程。如果打开后没反应绝大多数情况是路径不对autoload.js 默认找根目录的model文件夹不是models不是live2d目录名差一个字就加载不出来。3.2 用一台静态服务器预览为什么双击 HTML 会翻车现在关键一步来了不要直接双击 index.html 打开。用命令行起一个静态服务器python3 -m http.server 8080然后浏览器访问http://localhost:8080/。为什么要多此一举因为 autoload.js 在浏览器里是用 fetch 拉取模型 json 的而 fetch 在file://协议下会被浏览器的 CORS 策略直接拦截。双击 html 文件时页面地址是file:///...所有的本地模型资源请求全部失败控制台里会刷一堆红色报错页面白屏。起一个本地服务器后所有资源走 http 协议这条链路就通了。这个细节是新手翻车率最高的一步没有之一。3.3 model3.json 里必须校对的三类字段模型加载的核心是一个 json 配置Cubism 3/4/5 都是.model3.json。下载来的模型如果结构不完整九成问题都出在这个文件的路径引用上。打开它重点看三个字段字段指向内容路径基准FileReferences.Moc模型文件后缀 .moc3相对 json 所在目录FileReferences.Textures贴图数组相对 json 所在目录FileReferences.Motions动作动画列表相对 json 所在目录一个典型的配置是这样{ Version: 3, FileReferences: { Moc: maid.moc3, Textures: [textures/texture_00.png], Physics: maid.physics3.json, Motions: { Idle: [ { File: motions/idle_01.motion3.json } ] } } }这里的两个要点一是所有路径都是“相对于模型 json 所在的那个文件夹”不是相对于 html也不是相对于项目根目录二是如果模型自带物理效果Physics字段要指向.physics3.json这个文件缺失不会报错但角色的头发、裙子会硬得跟木板一样完全不动。下载来的模型如果挂掉先把这三个字段对着实际文件夹人工核对一遍比上网乱搜有效得多。4. 把看板娘调成你的形状位置、交互、台词与多模型切换跑通第一个模型只是起点接下来才是真正有意思的部分——让这个角色看起来像是“你的”。这一章讲四个常用自定义维度位置尺寸、点击反应、台词文本、多模型切换。4.1 位置、尺寸、透明度的参数组合live2d-widget 的配置入口是一个全局变量LIVE2D_WIDGET_OPTIONS在加载 autoload.js 之前定义。通过它可以把角色从“默认右下角”挪到任意位置也能控制缩放和透明度script window.LIVE2D_WIDGET_OPTIONS { modelPath: ./model/maid/, mobile: { show: true, scale: 0.6 }, display: { showHitArea: false, showFloatMenu: false }, react: { opacity: 0.8, radius: 0.8 }, menu: { show: true } }; /script script src./live2d-widget/autoload.js charsetutf-8/script参数的含义按用途拆开说modelPath指向模型文件夹注意末尾斜杠路径基准是当前 html 所在目录。mobile.show移动端是否显示看板娘。手机屏幕小默认关掉比较合理。mobile.scale整体缩放系数。桌面端改这个也有效0.5 就是缩到一半。display.showHitArea是否显示点击区域线框。调试交互定位时打开正式上线必须关掉否则一个难看的半透明色块会一直在角色上。react.opacity鼠标移近时角色的透明度变化。数值越低鼠标越靠近角色会越透明这个效果适合角色挡住页面内容时用。react.radius鼠标交互感应半径0.8 表示角色周围 80% 宽度的范围内鼠标移动都会让角色转头。menu.show是否显示右上角的小菜单按钮负责角色切换、隐藏等操作。这些参数建议一次只改一个然后刷新看效果。尤其是缩放和透明度改得太激进会让角色看起来像一块半透明的贴纸观感会很廉价。4.2 台词和命中区让角色对点击、抚摸有反应让看板娘“会说话”和“对不同部位有反应”是定制感提升最明显的两步。常靠一个waifu-tips.json来控制它的结构如下{ message: [ 今天也要加油呀, 别摸了快写代码, 再看我也不会帮你写 bug ], hit: { top: [头是不能乱摸的], middle: [肚子有点饿], bottom: [腿…腿不可以] } }message数组是鼠标空闲时随机冒出的台词hit对象分上中下三个区对应点击角色头部、身体、腿部时的反馈。这里最容易写错的是 JSON 语法多一个逗号、引号少一边整个配置文件加载失败角色会变成哑巴。编辑完建议丢进任意 JSON 校验工具过一遍再刷新页面。台词文本别写太长气泡会溢出三到八个字是最舒服的区间。另外这个文件也是社区模型整合包里的高频遗留物很多包里自带的台词是大白话或者原作者的口头禅替换成你自己的文本看板娘的“专属感”立刻就不一样了。4.3 多模型目录维护切换模型的最小脚本看板娘真正让人上瘾的是“随时换个角色上场”。做法也很朴素在 model 目录下放多个子目录每个子目录是一个完整模型。model/ ├─ maid/ │ ├─ maid.model3.json │ └─ textures/ ├─ miku/ │ ├─ miku.model3.json │ └─ textures/ └─ snow/ ├─ snow.model3.json └─ textures/切换模型的逻辑是最小化设计改modelPath然后重新初始化。由于 autoload.js 没有暴露一个优雅的销毁重建接口最简单的可靠方案是刷新页面function switchModel(name) { const opts window.LIVE2D_WIDGET_OPTIONS || {}; opts.modelPath ./model/ name /; location.reload(); }这段代码看着粗暴但实际上很有效刷新后页面会带着新配置重新初始化。如果不想刷新想要无缝切换就需要在初始化之前取消了旧 canvas 再重建不同版本 autoload.js 的接口不一样工作量和收益不成正比。我的习惯是把最近用的两三个模型放进 model 目录用菜单手动切不用写任何逻辑。5. 上线避坑看板娘部署的 5 个典型翻车现场“本地能跑”和“别处也能跑”是两码事。前面所有操作在 localhost 上跑通不代表换个环境还能正常。这章写五个我见过最多、也最容易让人血压升高的现场。5.1 白屏、半截模型、风扇狂转三个最常见的本地翻车点第一个翻车现场双击 index.html 打开一片白控制台全是红色的 CORS 报错。原因是 autoload.js 用 fetch 拉取本地 jsonfile://协议把请求全拦截了。解决方式是起一个 http 服务器python3 -m http.server 8080是零成本的做法。别问“为什么别人发的包能双击打开”别人只是把 json 写死成了全局变量或者用了老式的非模块写法这属于两个时代的架构不需要羡慕。第二个翻车现场模型加载出来了但只有半截或者角色整个悬在页面中间。原因是.model3.json里的Moc字段和Textures字段路径写错了。路径基准是“模型 json 所在的目录”不是项目根目录。很多从游戏提取出来的模型包json 是被改过的指向models/xxx/textures/...放进你自己的目录之后这个相对关系就断了。解决方式是打开 model3.json对照实际目录一层层改直到每个字段都能对上真实文件。第三个翻车现场页面流畅但 CPU 风扇开始怒吼。看板娘的 canvas 是实时渲染每一帧都在计算网格变形和物理模拟贴图超过 2048×2048 时开销非常明显。解决方式有三个任选其一把贴图从 4096 降到 2048在LIVE2D_WIDGET_OPTIONS里把mobile.scale或全局缩放调低把模型 json 里的Physics字段暂时去掉禁用物理模拟。这个翻车最容易被人忽略因为它不影响功能但会让用户觉得你的页面有毒。5.2 模型版本不兼容、状态丢失部署到博客后的问题第四个翻车现场从网上下载的 zip 包解压放进去结果控制台报 “moc3 model is not supported”。原因多半是模型是 Cubism 2 时代的.moc文件配的是model.json而 live2d-widget 这类浏览器封装只支持 Cubism 3 以上的.moc3.model3.json。判断方法很简单看配置文件名model.json是旧版model3.json是新版。解决方式有三个要么找同模型的 Cubism 3 导出包要么在 Cubism Editor 里打开旧工程重新导出.moc3要么换一个本身就是新格式的模型。强行让旧格式跑起来的方法不是没有但是要单独找 Cubism 2 的运行时投入产出比很低。第五个翻车现场部署到博客或者 GitHub Pages 后刷新页面角色永远回到右下角之前拖动的位置没保存。原因有两个层次一是位置记忆依赖 localStorage而 localStorage 是按域名隔离的localhost和正式域名各自存各自的换域名相当于失忆二是如果博客开启了隐私保护模式localStorage 直接不可写。解决方式是接受这个行为位置记忆本来就是个“尽力而为”的功能不需要为了它引入后端存储。我的做法是干脆固定把看板娘钉在右下角不做拖拽省掉所有记忆逻辑反而稳定。6. 再进一步让看板娘开口说话、与页面联动、接入 AI 出图流程跑通了上面几步看板娘已经从“一个会动的贴图”进化成了“一个会互动的角色”。最后再说三个我自己觉得增值明显的玩法。第一个是让角色开口说话。不需要接任何语音服务浏览器自带 speechSynthesis 接口几十行代码就能让台词变成语音const synth window.speechSynthesis; function speak(text) { const utterance new SpeechSynthesisUtterance(text); utterance.lang zh-CN; utterance.rate 1.0; synth.speak(utterance); }调用方式就是在点击事件里把台词文本传给 speak。这里有个小经验中文语音包是系统自带的但如果系统里装过多个中文语音合成效果差很多可以在 utterance 上指定 voice选一个听着顺耳的。第二个玩法是页面联动比如滚动到页面底部时触发一句“你都看到这了”夜间模式切换时给角色换一套暗色装扮。这类联动的实现方式都是从一个页面事件回调里调用看板娘的暴露方法事件源和角色行为完全解耦改动成本很低。第三个是大家越来越关心的话题有了 AI以后是不是不用 live2D 了我的看法是恰恰相反——AI 负责更好地产出差分立绘和表情帧但绑定骨骼、物理模拟、实时交互这套逻辑仍然要经过 Cubism 的工作流。合理路径是先用 AI 快速生成多个表情和部件的差分图再进 PS 抠图分层最后导入 Cubism 绑定。这让“自己做一个模型”的门槛从“会画画”降到了“会整理素材”但对 live2D 这层管道的需求并不会消失。我的最后一个习惯建议每下载一个模型就在它的目录里放一个 README.txt写三行东西——来源链接、授权范围、目录结构。这个习惯救过我很多次特别是几个月后想回头查“这个模型到底能不能往博客上挂”的时候不用再翻几十个浏览器标签页。看板娘这东西做出来不难难的是做成一个能长期维护的小项目。希望这些路线和坑能让你少走我走过的弯路希望帮到你。本文还有配套的精品资源点击获取