这次我们来看一个 Live2D 模型展示。主角是「森系美萌猫喵大小姐」整体走森系、可爱、猫娘主题角色配置包含猫耳、尾巴、铃铛这类常见 Live2D 装饰元素服装配色偏自然系和暖色系。这类模型常见于 VTuber 直播、网页互动展示、视觉小说和手机游戏。这篇不是单纯的“看图夸好看”而是把模型展示项目背后的技术链路完整拆开Live2D 模型文件长什么样、如何在网页里加载、怎么触发动作和表情、物理效果怎么配置、批量模型目录怎么检查、遇到加载失败怎么排查。无论你手上有没有这个模型都能用同一套流程去展示任何合规获取的 Live2D 素材。角色模型本身就是由大量分层、参数和动作数据组装出来的展示它的过程并不复杂但要注意的细节非常多model3.json 路径、纹理引用、动作组、物理模拟、WebGL 渲染每个环节都可能出问题。下面直接进入正文。1. 核心能力速览能力项说明项目类型Live2D 角色模型展示与交互角色主题森系美萌猫喵大小姐模型格式Live2D Cubism.moc3/.model3.json展示方式网页展示、Unity、VTube Studio 绑定交互能力点击触发动作、表情切换、头部追踪、物理效果编辑器Live2D Cubism Editor运行平台浏览器 / Windows / macOS / 移动端适合场景模型展示、直播、网页嵌入、Live2D 制作学习从技术角度看这个项目的重点不是一个复杂的后端服务而是把模型文件、渲染前端、交互逻辑三部分拼起来。只要模型文件完整浏览器就能直接跑起来门槛很低。核心难点在于理解 Live2D 模型的资源组织方式和运行时交互 API。2. 适用场景与使用边界先讲清楚什么场景适合用它什么场景不适合。适合个人模型展示页把角色放在网页里做一个可点击的看板娘。VTuber 直播通过 VTube Studio 等工具绑定模型再用摄像头驱动面部捕捉。视觉小说或游戏角色立绘使用 Live2D SDK 接入交互系统。Live2D 建模学习分析别人模型的图层、参数和动作设计。不适合需要真实景深和自由视角旋转的 3D 内容Live2D 本质是 2D 动画技术不是真正的 3D 模型。影视级特效和写实渲染Live2D 更擅长表现卡通和风格化角色。使用边界这是必须强调的部分。Live2D 模型是受版权保护的数字资产通常包含严格的授权条款一个角色模型的版权归属于原作者和角色版权方模型文件不一定允许二次分发、再上传或修改。即使是所谓“免费下载”的模型资源也可能只允许个人学习不允许直播商用或者打包进商业游戏。使用角色进行直播、视频或商业项目前要确认授权范围特别是“商用授权”和“修改授权”两项。涉及真人肖像、声音或特定 IP 角色时还需要额外的肖像权和 IP 授权。所以文章后面所有技术操作都建立在“模型是你自己制作、或已获得合法授权”的前提下。不要从不明来源下载模型后直接拿去直播和分发。3. 环境准备与前置条件本地展示 Live2D 模型需要准备以下几类环境3.1 浏览器环境推荐使用最新版 Chrome 或 Edge需要完整支持 WebGL 和 ES6 Module。Live2D 网页渲染依赖 WebGL如果浏览器禁用硬件加速或显卡驱动异常画面会卡成幻灯片的。3.2 本地运行环境虽然 Live2D 是前端渲染但为了加载本地模型文件建议起一个本地静态服务器。我推荐使用 Node.js 环境结构化组织更清晰node -v npm -v如果没有安装 Node.js也可以用 Python 自带的能力启动静态服务python3 -m http.server 8080两种方式选一种即可。Node.js 配合 Vite 更适合做后续交互扩展Python 适合快速测试。3.3 模型文件准备Live2D 模型不是单个图片文件而是一个目录结构。以 Cubism 3.0 以上版本为例完整模型通常包含models/miao/ ├── miao.model3.json ├── miao.moc3 ├── textures/ │ └── texture_00.png ├── motions/ │ ├── idle.motion3.json │ └── tap_body.motion3.json ├── expressions/ │ ├── happy.exp3.json │ └── shy.exp3.json └── physics/ └── physics3.json几个关键文件的作用miao.model3.json模型入口文件记录所有其他资源的路径相当于索引清单。miao.moc3模型核心数据包含网格、图层、参数定义是模型真正的主体。textures/角色的贴图文件通常是一张或多张 PNG。motions/动作文件描述角色执行某个动作时参数的动态变化。expressions/表情文件比如开心、害羞、眨眼等。physics/物理模拟文件控制头发、尾巴、衣服等部位的摆动效果。如果资源引用路径有误模型就加载不出来这是最常见的坑后面排查部分重点讲。3.4 Live2D Cubism 编辑器可选想自己制作或修改模型需要安装 Live2D Cubism Editor。这是官方编辑器用于调整网格、参数权重、动作曲线和物理效果。Cubism Editor 不是免费软件但官方提供试用版本使用前注意确认许可协议。学习阶段用试用版熟悉建模流程足够。如果你只做模型展示不修改模型那么第三方的网页展示方案就够了。4. 模型文件结构与一键启动展示这里用pixi-live2d-display作为展示库。它是 Live2D 网页展示社区里使用很广泛的方案底层基于 PixiJS能够把.model3.json直接加载成场景中的一个显示对象。4.1 初始化项目mkdir live2d-showcase cd live2d-showcase npm init -y npm install pixi.js pixi-live2d-display npm install -D vite在package.json中配置启动脚本{ scripts: { dev: vite, build: vite build, preview: vite preview } }4.2 项目目录结构把模型文件放到public/models目录下live2d-showcase/ ├── index.html ├── main.js ├── package.json └── public/ └── models/ └── miao/ ├── miao.model3.json ├── miao.moc3 ├── textures/ └── motions/Vite 会把public目录下的文件原样作为静态资源提供所以最终访问路径是/models/miao/miao.model3.json。4.3 创建入口页面index.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleLive2D 模型展示 - 森系美萌猫喵大小姐/title style html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; background: linear-gradient(160deg, #e9f2e3 0%, #f7f2e8 60%, #fdeee0 100%); } #canvas { display: block; width: 100%; height: 100%; } /style /head body canvas idcanvas/canvas script typemodule src/main.js/script /body /html背景用渐变模拟“森系”氛围实际展示时可以根据自己角色风格调整。4.4 编写加载逻辑main.jsimport { Application } from pixi.js; import { Live2DModel } from pixi-live2d-display; // 兼容性设置pixi-live2d-display 内部需要读取全局 PIXI window.PIXI { Application }; const app new Application({ view: document.getElementById(canvas), backgroundAlpha: 0, resizeTo: window, antialias: true }); // 加载模型 const model await Live2DModel.from(/models/miao/miao.model3.json); // 添加到舞台 app.stage.addChild(model); // 初始位置和缩放 model.anchor.set(0.5, 1); model.scale.set(0.4); model.x app.screen.width / 2; model.y app.screen.height; // 点击模型本体触发动作 model.on(hit, (hitAreas) { if (hitAreas.includes(Body)) { model.motion(tap_body); } }); // 窗口尺寸变化时保持在底部居中 window.addEventListener(resize, () { model.x app.screen.width / 2; model.y app.screen.height; });启动本地服务npm run dev浏览器打开终端输出的地址默认一般是http://localhost:5173。如果模型文件完整页面刷新后就能看到角色出现在页面底部。这里显存占用和模型尺寸直接相关一般 2D 角色模型占用很低重点观察的是 GPU 解码贴图和 WebGL 渲染的开销。5. 功能测试与效果验证模型能显示只是第一步接下来要逐项验证动作、表情、物理和交互。5.1 模型加载测试测试目的确认 model3.json 能被正确解析所有资源引用无缺失。操作步骤启动服务后打开浏览器控制台。刷新页面观察main.js是否有报错。在 Network 面板查看模型目录下所有资源的加载状态。预期结果miao.model3.json和miao.moc3返回 200。所有 PNG 贴图正常加载。页面出现角色模型。判断标准控制台无红色报错模型完整显示。常见失败原因路径大小写不一致比如Textures目录写成了/texture。model3.json 中的相对路径不对。模型文件本身损坏或版本过旧。5.2 动作触发测试测试目的验证模型动作组是否正常。在模型加载完成后在控制台手动执行model.motion(tap_body);如果模型有多个动作组可以查看model3.json中Motions字段配置了哪些组{ Motions: { Idle: [ { File: motions/idle.motion3.json } ], TapBody: [ { File: motions/tap_body.motion3.json } ] } }预期结果模型播放对应动作比如挥手、歪头等播放完成后自动回到待机状态。判断标准动作一次性完成没有肢体穿模和突然跳变。这里要提醒一句不同模型的动作组命名不一样tap_body只是常见命名。如果调用model.motion(tap_body)没反应先打开model3.json看真实动作组名称。5.3 表情与参数控制表情文件定义在Expressions字段中。加载模型后可以通过 PixiJS 的触摸或鼠标事件来切换表情。model.expression(happy);手动调整模型参数model.internalModel.coreModel.setParameterValueById(ParamAngleX, 15); model.internalModel.coreModel.setParameterValueById(ParamEyeLOpen, 0.8); model.internalModel.coreModel.setParameterValueById(ParamMouthOpenY, 0.5);通过调整ParamAngleX、ParamEyeLOpen、ParamMouthOpenY这类标准参数可以验证模型的眼睛、嘴巴、头部朝向是否正常。预期结果表情切换流畅参数变化时对应部位跟着变化。判断标准眼睛能正常睁开闭合头部能左右转动嘴巴开合幅度自然。5.4 物理效果测试头发、猫耳、尾巴这类部位如果没有物理效果模型看起来就会很僵。验证方式确定model3.json的FileReferences.Physics字段指向了physics3.json。拖动模型或点击触发动作观察头发和尾巴是否轻微摆动。在浏览器控制台执行model.focus(0.5, 0.2);这会把模型视线焦点移动到一个位置配合头部角度参数观察是否存在自然延迟。判断标准头发不是硬邦邦地跟随头部移动而是有惯性延迟和回弹幅度自然不夸张。5.5 批量模型完整性检查如果手上有很多模型文件在展示前可以用一个脚本批量扫描检查每个模型的资源引用是否完整。这是一个很实用的小工具。创建scripts/check-models.cjsconst fs require(fs); const path require(path); const modelsDir path.resolve(__dirname, ../public/models); function checkModel(dir) { const files fs.readdirSync(dir); const model3 files.find(f f.endsWith(.model3.json)); if (!model3) { return { model: path.basename(dir), ok: false, message: 缺少 .model3.json 文件 }; } const fullPath path.join(dir, model3); const json JSON.parse(fs.readFileSync(fullPath, utf-8)); const refs json.FileReferences; if (!refs) { return { model: model3, ok: false, message: 缺少 FileReferences 字段 }; } const missing []; const addMissing (file) { if (file !fs.existsSync(path.join(dir, file))) { missing.push(file); } }; addMissing(refs.Moc); (refs.Textures || []).forEach(addMissing); if (refs.Motions) { Object.values(refs.Motions).flat().forEach(item { if (item item.File) addMissing(item.File); }); } if (refs.Physics) addMissing(refs.Physics); if (refs.Expressions) { refs.Expressions.forEach(item { if (item item.File) addMissing(item.File); }); } return { model: model3, ok: missing.length 0, missing: missing.join(, ) || - }; } const dirs fs.readdirSync(modelsDir, { withFileTypes: true }) .filter(d d.isDirectory()) .map(d path.join(modelsDir, d.name)); const results dirs.map(checkModel); console.table(results);运行node scripts/check-models.cjs输出一个表格每个模型资源引用是否有问题一目了然。这个脚本的价值在于从网上下载的模型经常丢贴图或运动文件手动肉眼检查很容易漏。6. 接口 API 与扩展集成pixi-live2d-display提供了几个核心 API在展示项目里会反复用到。6.1 核心 API 说明API作用Live2DModel.from(path)从 model3.json 路径加载模型model.motion(name)触发某个动作组model.expression(name)切换表情model.anchor.set()设置模型锚点位置model.scale.set()设置模型缩放model.focus(x, y)把视线焦点移到屏幕坐标位置model.on(hit)监听模型命中区域检测事件其中hit事件是交互的核心。点击模型时Live2D 会自动判断点击命中了哪个区域区域名称来自模型中的命中区域定义比如Head、Body、CatEar等。不同模型的命中区域定义不同可以先在控制台把命中区域名打印出来model.on(hit, (hitAreas) { console.log(hitAreas); });6.2 扩展为看板娘把模型嵌到任意网页右上角或左下角做成看板娘是很常见的用法。核心逻辑就是把舞台叠加到页面上然后保持模型常驻import { Live2DModel } from pixi-live2d-display; import * as PIXI from pixi.js; window.PIXI PIXI; async function loadBoardModel() { const app new PIXI.Application({ width: 300, height: 400, transparent: true, resizeTo: undefined }); const view app.view; view.style.position fixed; view.style.bottom 0; view.style.right 20px; view.style.zIndex 9999; view.style.pointerEvents none; document.body.appendChild(view); const model await Live2DModel.from(/models/miao/miao.model3.json); app.stage.addChild(model); model.scale.set(0.3); model.x 150; model.y 400; model.anchor.set(0.5, 1); setInterval(() { const r Math.random(); if (r 0.3) model.motion(Idle); if (r 0.15) model.expression(happy); }, 8000); } loadBoardModel();注意pointerEvents: none这段。如果希望模型能被点击需要把pointerEvents设为auto否则命中检测收不到鼠标事件。6.3 接入 VTube Studio 或 Unity网页方案适合展示和看板娘场景。如果要做直播更成熟的路线是用 VTube Studio 加载模型通过摄像头驱动面部捕捉。把模型导出到 Unity 工程用官方 Cubism SDK for Unity 做复杂的交互场景开发。VTube Studio 面向普通用户界面操作比写代码简单把模型目录放进它的模型目录启动后会自动扫描。这种方法适合需要直播的用户。Unity 方案适合游戏项目可编程性更强但需要熟悉 Unity 工程结构和 Cubism SDK 生命周期。7. 资源占用与性能观察Live2D 模型展示是纯前端渲染不像视频生成或大模型推理那样吃显存但仍要注意几项性能指标。7.1 观察方法打开浏览器开发者工具切到 Performance 面板点击录制然后操作模型观察FPS 是否稳定在 60。每一帧的 GPU 渲染时长。是否有长任务导致的掉帧。Memory 面板可以看贴图和 WebGL 缓冲区的内存占用。模型贴图数量越大、单张贴图分辨率越高内存占用越高。Live2D 模型的贴图通常是 2048x2048 或 4096x4096 的 PNG多个贴图叠加会让内存压力变大。7.2 影响性能的主要因素贴图分辨率贴图越大GPU 采样成本越高。展示大模型时建议检查贴图尺寸是否合理2048 足够大多数角色使用。模型复杂度网格顶点数量和图层数会影响 CPU 侧的骨骼计算和参数计算。物理模拟physics3.json中物理点越多每帧的力学计算开销越大。透明度渲染Live2D 模型通常带透明效果渲染顺序错误或叠加过多透明层会增加 overdraw。多模型同屏一次加载多个模型每帧的绘制调用会成倍增加。7.3 降低性能压力的方法// 关闭 Vertex Scale 相关功能适合低端设备 model.internalModel.coreModel.getModel().parameterValues;最直接的优化手段给模型设置model.visible false做懒加载只有出现在视口时才显示。后台 tab 暂停渲染document.addEventListener(visibilitychange, () { if (document.hidden) { app.stop(); } else { app.start(); } });降低像素比const app new PIXI.Application({ view: document.getElementById(canvas), backgroundAlpha: 0, resizeTo: window, resolution: Math.min(window.devicePixelRatio, 2) });7.4 显存与内存的观察逻辑网页渲染的显存占用不直接显示在任务管理器里更可靠的方式是使用 Chrome 的chrome://gpu或者开发者工具的Page / WebGL相关指标。观察时主要看 GPU Memory 曲线是否有持续上涨如果持续上涨说明存在纹理泄漏可能与模型频繁加载和销毁有关。8. 常见问题与排查方法这里列一下 Live2D 模型展示最常见的问题和排查方向。问题现象可能原因排查方式解决方案页面空白模型不显示model3.json 路径错误或资源缺失打开 Network 面板看 404修正路径运行批量检查脚本模型显示但纯白色贴图加载失败或 WebGL 上下文问题检查 texture 请求状态确认贴图存在刷新页面点击模型没反应命中区域配置缺失或pointerEvents为 none控制台打印hit事件开启指针事件检查 model3.json 的 HitAreas动作叫tap_body没触发动作组名称不对查看 model3.json 的 Motions使用模型实际动作组名称模型无法播放表情expression 名称拼错查看 Expressions 字段使用模型实际表情文件名称头发和尾巴没有摆动physics3.json 缺失或未引用检查 FileReferences.Physics补全物理文件并检查模型中的物理配置模型显示特别小或特别大锚点和缩放未设置调整 scale 和 anchor小步调整 scale从 0.2 到 1 之间试浏览器报 WebGL context lost浏览器驱动或显卡兼容问题chrome://gpu 检查 WebGL 状态更新显卡驱动关闭硬件加速再试低端设备卡顿贴图过大或物理模拟复杂Performance 面板定位耗时降低贴图分辨率降低 devicePixelRatio模型加载后音效反复触发动作配置里有声音循环查看 motion3.json 的 Sound删除 Sound 字段或替换为空文件Node.js 安装依赖失败网络或 npm 镜像问题查看 npm 报错信息切换 npm 镜像源重试其中最常见、也是新手最容易忽略的是路径问题。model3.json中的所有路径都是相对当前文件位置的相对路径不是绝对路径也不是相对项目根目录的路径。很多模型在压缩包内可以正常用一旦解压到public/models下某个子目录路径就全部失效了。9. 最佳实践与使用建议9.1 模型目录管理把模型目录按角色名组织保持固定结构public/models/ ├── miao_cat/ │ ├── miao_cat.model3.json │ └── textures/ ├── forest_lady/ │ └── ... └── README.md每个模型目录内只保留模型相关文件不把源工程 PSD、Cubism 工程文件混进来。展示用的模型目录越干净排查路径问题越轻松。建议写一个README.md记录模型名称和角色设定。授权类型是否允许商用、是否允许修改。来源信息。动作组清单和表情清单。这对于后续再次使用非常有价值。否则三天后你自己都会忘掉这个模型有哪些动作。9.2 第一次先小参数测试第一次写展示页时不要直接追求“完美打开”。流程应该是先用一个最简页面加载模型确认能显示。再添加缩放和锚点调整位置。然后加动作触发。最后加表情、物理、点击交互。每一步单独验证出现问题范围就很小。如果一口气写完整个展示页再调试报错来源会非常分散。9.3 输出目录和日志如果是批量展示多个模型建议在页面右上角显示当前模型名称和授权状态。真做商用或多模型切换时在控制台统一输出加载结果console.log([LoadModel] ${model.url} - success, size${model.width}x${model.height});这样批量切换模型时可以在日志里快速定位哪个模型加载失败。9.4 合规使用记录这是最容易在项目中忽略的部分。使用任何一个 Live2D 模型建议保留授权记录。展示页面可以放一个授权说明面板注明模型作者、授权方式和 iframe 链接。直播前确认模型允许直播使用。商用前一定要拿到书面或明文授权。9.5 多设备兼容性测试PC 上显示正常不代表手机上正常。Live2D 展示页至少要在电脑 Chrome/Edge。iOS Safari。Android Chrome。各打开一次。重点看 WebGL 支持和触摸事件。移动端的点击事件和 PC 的鼠标事件在hit处理上可能不完全一致实际部署前务必真机验证一次。10. 总结与下一步「森系美萌猫喵大小姐」这种模型本质上考验的不是模型展示代码的复杂度而是三件事模型资源是否完整、路径是否配置正确、交互触发是否命中正确的动作和表情组。最先应该验证的是模型加载这一步能通过后面所有交互都好说。最容易踩的坑是路径model3.json 相对路径、纹理路径、动作路径任何一个写错都是 404。如果动作触发和表情切换不生效优先打开 model3.json 看真实名称不要猜。如果后续想继续扩展可以往这几个方向走把模型接入 VTube Studio用摄像头驱动面部和头部转向。把模型嵌入企业官网或个人博客做常驻看板娘并在空闲状态循环播放待机动作。学习 Live2D Cubism Editor直接用这个模型当参考理解图层拆分、网格构建、参数权重和物理效果。Live2D 模型展示上手难度很低但要把交互做得自然、稳定、好看还是需要多花时间调参数和物理效果。建议先把 5.1 到 5.4 的测试流程完整走一遍再考虑优化和扩展。