网页看板娘开发Skill

Live2D 桌宠集成排坑指南

概述

在 React + Vite 项目中集成 Live2D 桌宠时，核心难点不在于使用 API，而在于库版本兼容性和运行环境差异。本技能记录从零到成功的完整踩坑过程和正确方案。

核心教训

错误的方案：pixi-live2d-display + 项目已有 PixiJS v7

失败原因：pixi-live2d-display v0.4.0 基于 PixiJS v6 构建，而项目中已安装 PixiJS v7。

pixi-live2d-display (v6 构建) + PixiJS v7 → Shader 兼容性错误
错误信息：Invalid value of '0' passed to 'checkMaxIfStatementsInShader'

PixiJS v7 引入了更严格的 shader 检查（checkMaxIfStatementsInShader），Live2D 的复杂 shader 无法通过该检查。尝试设置 settings.MAX_IF_STATEMENTS_IN_SHADER = 1000 无效，因为 shader 在模块加载阶段已编译。

正确的方案：oh-my-live2d（v0.19+）

推荐使用 oh-my-live2d（npm 包），原因：

1. 内置 PixiJS v6：自己打包了完整 PIXI v6 运行时，不依赖项目中的 PIXI 版本
2. 内置 Cubism2 SDK：以 inline script 方式注入，不依赖外部 CDN（v0.19+ 已修复 CDN 依赖问题）
3. API 简单：只需 loadOml2d({ models: [...] }) 即可完成初始化

import { loadOml2d } from 'oh-my-live2d';

const oml2d = loadOml2d({
  dockedPosition: 'right',   // 靠右显示
  models: [{
    name: 'Pio',
    path: '/live2d/pio/model.json',  // 模型 JSON 的 public 路径
    scale: 0.08,
    position: [0, 20],
  }],
  statusBar: { disabled: true },
  menus: { disabled: true },
  tips: { disabled: true },
});

模型文件结构

模型文件放在 public/live2d/<name>/ 目录下：

public/live2d/pio/
├── model.json    # 模型配置（入口文件）
├── model.moc     # 模型二进制数据
├── textures/     # 贴图目录
└── motions/      # 动作/动画目录

model.json 中的 path 字段即为完整的 public 路径："/live2d/pio/model.json"。

调试方法

渐进式状态显示

Live2D 初始化是异步过程，出错时往往静默失败。必须在组件中显示加载状态和错误信息，否则无法定位问题：

const [status, setStatus] = useState('loading...');
const [error, setError] = useState('');

// 每个关键步骤更新 status：
// 'step0 (SDK)' → 'step1 (pixi)' → 'step2 (l2d)' → 'step3 (app)' → 'step4 (model)' → 'done'

// 渲染调试面板：
{error ? <div style={{...红框}}>{error}</div> : 
 status !== 'done' ? <div style={{...黑框}}>{status}</div> : null}

排查顺序

1. 先去掉可疑组件，确认页面本身能正常渲染
2. 逐步添加回来，通过 status 定位卡在哪一步
3. 看到错误信息后，逐层排查

PixiJS 版本对照表

库	PixiJS 版本	说明
pixi-live2d-display v0.4.0	v6	peer deps 声明为 @pixi/*@^6
oh-my-live2d v0.19+	v6（内置）	不依赖项目中的 PIXI，零冲突
项目中的 pixi.js v7	v7	与 pixi-live2d-display 不兼容

常见错误及解决方案

错误	原因	解决
Invalid value of '0' passed to 'checkMaxIfStatementsInShader'	PixiJS v7 不支持 Live2D shader	换用 oh-my-live2d（内置 v6）
本地正常，远端不显示桌宠	oh-my-live2d 旧版依赖 unpkg CDN	升级到 v0.19+（SDK 已内置）
页面完全空白	组件崩溃导致 React 不渲染	先注释掉组件，逐步排查
live2d.min.js must be loaded before pixi-live2d-display/cubism2	Cubism2 SDK 未加载	oh-my-live2d 已内置，无需手动加载
桌宠不显示但无报错	错误被静默捕获	添加状态显示，暴露错误信息

关键代码模板

React 组件骨架

import { useEffect, useRef, useState } from 'react';
import { loadOml2d } from 'oh-my-live2d';

export default function MascotLive2D() {
  const initializedRef = useRef(false);
  const [status, setStatus] = useState('loading...');
  const [error, setError] = useState('');

  useEffect(() => {
    if (initializedRef.current) return;
    initializedRef.current = true;

    (async () => {
      try {
        const oml2d = loadOml2d({
          dockedPosition: 'right',
          models: [{ path: '/live2d/pio/model.json', scale: 0.08 }],
          statusBar: { disabled: true },
          menus: { disabled: true },
          tips: { disabled: true },
        });
        setStatus('done');
      } catch (e) {
        setError(e.message);
      }
    })();
  }, []);

  // 调试面板（生产环境可移除）
  if (error) return <ErrorDisplay error={error} />;
  if (status !== 'done') return <LoadingDisplay status={status} />;
  return null; // oh-my-live2d 自行管理 DOM
}

不要做的事情

1. 不要混用 oh-my-live2d 和 pixi-live2d-display —— 它们是互斥的方案
2. 不要手动加载 live2d.min.js —— oh-my-live2d 已内置
3. 不要在 oh-my-live2d 组件中同时渲染 canvas —— 它自己管理 DOM
4. 不要静默捕获错误 —— 始终提供可见的状态反馈
5. 不要假设 PixiJS 版本兼容 —— 始终检查库的 peer dependencies