前言
给博客添加一个可爱的 Live2D 看板娘，是很多个人站点的经典配置。本文将介绍如何在 Hugo 博客中基于 l2d-widget 库集成初音未来 Live2D 模型，并实现丰富的交互功能。
效果概览
集成后的功能包括：
| 功能 | 说明 |
|---|---|
| 🎭 模型展示 | 初音未来 Live2D 模型，支持完整物理和动作 |
| 🏠 自定义菜单 | 悬浮菜单栏，包含首页、关于、标签、归档、留言、友链、RSS 等导航 |
| 💬 提示气泡 | 欢迎语 + 循环提示，逐字打字动画 |
| 👄 嘴型同步 | 提示文字逐字显示时驱动模型嘴巴开合 |
| 😴 休眠模式 | 点击休息按钮隐藏模型，底部状态条可唤醒 |
| 📱 移动端适配 | 可配置移动端是否显示，控制更灵活 |
| ⚙️ 后台管理 | 管理面板可开关和控制各项参数 |
技术选型
经过对多种 Live2D 方案的调研和实测，最终选用 l2d-widget：
| 方案 | 状态 | 原因 |
|---|---|---|
pixi-live2d-display + pixi.js | ❌ 放弃 | PixiJS v6 UMD 构建在 CDN 不可用 |
oh-my-live2d | ❌ 放弃 | 已改名为 l2d-widget，旧版 API 废弃 |
l2d-widget | ✅ 选用 | 零依赖、~500行、IIFE 直接可用、支持 Cubism 3+ |
l2d-widget 通过 CDN 引入，一个 createWidget() 调用即可完成 canvas 创建、WebGL 上下文、模型加载和交互绑定。
1<script src="https://cdn.jsdelivr.net/npm/l2d-widget@0.0.2/dist/index.min.js"></script>
集成步骤
1. 准备模型文件
下载初音未来 PRO 版模型（Cubism 3 格式），将以下文件放入 static/live2d/miku/ 目录：
1static/live2d/miku/
2├── miku_sample_t04.model3.json
3├── miku_sample_t04.moc3
4├── miku_sample_t04.physics3.json
5├── miku_sample_t04.cdi3.json
6├── miku_sample_t04.2048/
7│ └── texture_00.png
8└── motion/
9 └── *.motion3.json
2. 创建模板部件
在 layouts/partials/live2d.html 中编写渲染逻辑：
1{{ if site.Params.live2d.enable }}
2<script src="https://cdn.jsdelivr.net/npm/l2d-widget@0.0.2/dist/index.min.js"></script>
3
4<script>
5(function() {
6 var isMobile = /Android|iPhone|iPad|iPod|webOS/i.test(navigator.userAgent)
7 || window.innerWidth < 768;
8 {{ if not site.Params.live2d.mobile }}
9 if (isMobile) return;
10 {{ end }}
11
12 var baseWidth = {{ site.Params.live2d.width | default 280 }};
13 var baseHeight = {{ site.Params.live2d.height | default 250 }};
14 var pos = "{{ site.Params.live2d.position | default "left" }}";
15
16 window.L2D_WIDGET.createWidget({
17 model: {
18 path: "{{ site.Params.live2d.model }}",
19 tips: {
20 welcomeMessage: ['欢迎来到我的博客！', '很高兴见到你～'],
21 messages: ['记得多来看看我哦～', '戳我一下试试～'],
22 duration: 4000,
23 interval: 6000,
24 typing: { param: 'PARAM_MOUTH_OPEN_Y', speed: 200 }
25 }
26 },
27 position: pos === 'right' ? 'bottom-right' : 'bottom-left',
28 size: { width: baseWidth, height: baseHeight },
29 menus: {
30 items: [
31 { label: '首页', icon: 'mdi:home',
32 onClick: function() { window.location.href = '/'; } },
33 { label: '关于', icon: 'mdi:information',
34 onClick: function() { window.location.href = '/about/'; } },
35 { label: '标签', icon: 'mdi:tag-multiple',
36 onClick: function() { window.location.href = '/tags/'; } },
37 { label: '归档', icon: 'mdi:archive',
38 onClick: function() { window.location.href = '/archives/'; } },
39 { label: '留言', icon: 'mdi:comment',
40 onClick: function() { window.location.href = '/guestbook/'; } },
41 { label: '友链', icon: 'mdi:account-group',
42 onClick: function() { window.location.href = '/friends/'; } },
43 { label: 'RSS', icon: 'mdi:rss',
44 onClick: function() { window.open('/index.xml', '_blank'); } },
45 { label: '休息', icon: 'mdi:sleep',
46 onClick: function(w) { w.sleep(); } }
47 ]
48 }
49 });
50})();
51</script>
52{{ end }}
3. 引入到页面
在 layouts/_default/baseof.html 的 </body> 前插入：
1{{ partial "live2d.html" . }}
4. Hugo 配置
在 hugo.toml 中添加配置段：
1[params.live2d]
2 enable = true
3 model = "/live2d/miku/miku_sample_t04.model3.json"
4 position = "left" # left | right
5 scale = 1.0
6 width = 280
7 height = 250
8 mobile = false # 移动端是否显示
5. 后台管理
在后台管理面板的「多媒体与挂件」Tab 中添加 Live2D 配置区域，支持开关控制、位置切换、尺寸调节、移动端显隐等参数，修改后自动同步到 hugo.toml。
自定义菜单
默认的感叹号按钮被替换为 8 个实用导航菜单：
- 首页 — 跳转首页
- 关于 — 跳转关于页
- 标签 — 跳转标签页
- 归档 — 跳转归档页
- 留言 — 跳转留言板
- 友链 — 跳转友链页
- RSS — 新窗口打开 RSS
- 休息 — 隐藏看板娘，底部留唤醒条
提示气泡与嘴型同步
通过 l2d-widget 的 tips 配置，实现了打字动画与嘴型参数的实时驱动：
welcomeMessage：首次加载时随机展示欢迎语messages：循环展示提示文字，间隔 6 秒typing.param：PARAM_MOUTH_OPEN_Y嘴型开合参数typing.speed：200ms/字，打字同时嘴巴开合
常见问题
模型不显示
检查 model3.json 文件路径是否正确，确认模型文件在 static/ 目录下可访问。
尺寸太小
l2d-widget 的 size 控制 canvas 尺寸，model.scale 控制内部渲染比例。注意不要双重缩放——size 用实际像素值，scale 单独控制。
移动端不隐藏
确保 hugo.toml 中 mobile = false，模板中的 isMobile 检测会阻止 widget 初始化。
总结
通过 l2d-widget 零依赖方案，仅需一个 CDN 脚本和一个函数调用，即可为博客添加完整功能的 Live2D 看板娘。配合 Hugo 模板变量和后台配置，实现了开箱即用、后台可控的看板娘系统。
留言评论
期待你的想法评论加载中