三月七 Live2D 展示

基于 Vue 3 + Vite + oh-my-live2d 在浏览器里渲染《原神》角色「三月七」Live2D 模型的极简示例。

特性

• 纯前端，零后端依赖
• CubismCore + PIXI 已内置打包，不依赖任何外网 CDN
• 鼠标跟随、自动眨眼、自动呼吸
• 4 套背景主题切换
• 实时缩放控制
• 可拖拽 / 点击触发动作

技术栈

库	版本	作用
vue	^3.4	UI 框架
vite	^5.2	构建/开发服务器
oh-my-live2d	^0.19.3	Live2D 渲染（内置 PIXI 6 + CubismCore WASM）

目录结构

sanyueqi-live2d-web/
├── public/
│   └── model/                  # 原封不动的 Live2D 模型资源
│       ├── 37.moc3             # 核心模型文件
│       ├── 37.model3.json      # 入口配置
│       ├── 37.physics3.json    # 物理参数
│       ├── 37.cdi3.json        # 显示信息
│       ├── 37.4096/            # 贴图（texture_00/01.png）
│       └── *.exp3.json / *.motion3.json
├── src/
│   ├── App.vue                 # 页面 + 控制面板
│   ├── main.js                 # 应用入口
│   └── style.css               # 全局样式
├── index.html
├── vite.config.js
└── package.json

快速开始

环境要求

• Node.js ≥ 18
• npm ≥ 9

安装并运行

# 1. 安装依赖
npm install

# 2. 启动开发服务器（默认 http://localhost:5173）
npm run dev

# 3. 构建生产版本到 dist/
npm run build

# 4. 本地预览生产构建
npm run preview

配置说明

模型加载的核心配置在 src/App.vue 的 loadOml2d() 调用里：

loadOml2d({
  parentElement: stageRef.value,    // 挂载点
  primaryColor: '#ff5e8a',           // 主题色
  models: [
    {
      name: 'sanyueqi',
      path: '/model/37.model3.json', // 模型入口（必须）
      scale: 0.1,                    // 模型缩放
      position: [0, 0],              // 模型位置
      motionPreloadStrategy: 'IDLE'  // 动作预加载策略
    }
  ],
  // 隐藏不需要的 UI
  statusBar: { style: { display: 'none' } },
  menus: { items: [] },
  tips: { style: { display: 'none' } }
})

替换为其他 Live2D 模型

1. 把新模型的整个文件夹放进 public/model/（或任意静态路径）
2. 找到入口 .model3.json 文件（Cubism 4）或 .model.json（Cubism 2）
3. 修改 src/App.vue 里的 path 字段指向新入口

path: '/model/your_model/xxx.model3.json'

背景主题

内置 4 套渐变背景，可在右上角面板切换。自定义只需修改 backgrounds 数组：

const backgrounds = [
  { gradient: 'linear-gradient(135deg, #xxx 0%, #yyy 100%)' },
  // ...
]

故障排查

页面空白 / 模型不显示

1. 打开浏览器 F12 控制台查看错误
2. 确认 /model/37.model3.json 能被访问（Network 面板应返回 200）
3. 如果看到 Could not find Cubism 4 runtime 错误，说明 oh-my-live2d 版本过低或安装不完整，重装依赖：

   rm -rf node_modules package-lock.json
   npm install

模型太小 / 太大

调整 models[0].scale 参数（默认 0.1），或点击右侧面板的放大/缩小按钮。

端口被占用

Vite 会自动切换端口（5174、5175...），查看终端输出确认实际地址。

常用 npm 脚本

命令	说明
npm run dev	启动开发服务器（HMR）
npm run build	打包到 dist/
npm run preview	预览生产构建

致谢与版权

• 模型来源：vinnelu/37live2d
• 模型版权：miHoYo（米哈游） 所有
• Live2D 渲染：oh-my-live2d (MIT)

使用条款（来自原仓库）

1. 本模型版权归属于 miHoYo
2. 使用时需符合原神官方的二创规定
3. 禁止商业用途 / 直播盈利 / 二次配布 / 政治·宗教相关内容
4. 本仓库仅供学习与技术交流，不承担任何连带责任

License

本仓库代码（Vue 工程部分）以 MIT 协议开源；模型资源版权归原作者所有。