文章目录
- 前言
- [什么是 Live2D?](#什么是 Live2D?)
- 方案一:简单版(快速部署单一模型)
- [方案二:进阶版(多模型 + 自定义交互)](#方案二:进阶版(多模型 + 自定义交互))
- 方案三:完全版(高度自定义功能)
- 注意事项
前言
在个人博客中加入 Live2D 看板娘,能让静态页面瞬间充满活力,提升访客互动感。本文整理了三种在 Hexo+Butterfly 主题中添加 Live2D 看板娘的方案,从快速部署到高度自定义,适合不同需求的开发者。
什么是 Live2D?
Live2D 是一种将 2D 插画转化为动态互动形象的技术,通过骨骼绑定和动画逻辑,让平面图像实现类似 3D 的立体动态效果。其官方 SDK 名为 Cubism,目前主要有 2/3/4/5 版本(不同版本支持的模型格式不同,例如 Cubism5 不支持 Cubism2 模型)。
方案一:简单版(快速部署单一模型)
适合新手入门,基于hexo-helper-live2d
插件实现,步骤简单,单一模型展示。
安装步骤
-
安装核心插件
在 Hexo 根目录(
[BlogRoot]
)打开终端,执行以下命令安装插件:
bash
npm install --save hexo-helper-live2d
-
配置站点配置文件
打开
[BlogRoot]\_config.yml
(站点配置文件),在底部添加或修改以下配置(按注释调整参数):
yaml
# Live2D配置
# https://github.com/EYHN/hexo-helper-live2d
live2d:
enable: true # 启用看板娘
scriptFrom: local # 默认,脚本来源(本地)
pluginRootPath: live2dw/ # 插件在站点上的根目录(相对路径)
pluginJsPath: lib/ # 脚本文件相对与插件根目录路径
pluginModelPath: assets/ # 模型文件相对与插件根目录路径
# scriptFrom: jsdelivr # jsdelivr CDN
# scriptFrom: unpkg # unpkg CDN
# scriptFrom: https://npm.elemecdn.com/live2d-widget@3.x/lib/L2Dwidget.min.js # 你的自定义 url
tagMode: false # 标签模式, 是否仅替换 live2d tag标签而非插入到所有页面中
debug: false # 调试, 是否在控制台输出日志
model:
use: live2d-widget-model-wanko # npm-module package name 默认模型
# use: wanko # 博客根目录/live2d_models/ 下的目录名
# use: ./wives/wanko # 相对于博客根目录的路径
# use: https://npm.elemecdn.com/live2d-widget-model-wanko@1.0.5/assets/wanko.model.json # 你的自定义 url
display:
position: right # 显示位置(left/right)
width: 150 # 看板娘宽度
height: 300 # 高度
mobile:
show: true # 移动端显示

-
生效配置
执行以下命令重新生成页面,访问
localhost:4000
即可查看效果。
bash
hexo cl && hexo g && hexo s # 清除缓存 -> 生成静态文件 -> 启动本地服务
更换模型
- 安装新模型(以
shizuku
为例):
bash
npm install --save live2d-widget-model-shizuku

- 修改
_config.yml
中model.use
为新模型名称:
yaml
model:
use: live2d-widget-model-shizuku # 替换为新模型名
# 默认为live2d-widget-model-wanko
- 重新执行
hexo cl && hexo g && hexo s
生效。
卸载方法
bash
# 卸载插件
npm uninstall hexo-helper-live2d
# 卸载指定模型(替换modelname为模型名)
npm uninstall live2d-widget-model-modelname
卸载后为了保证配置项不出错,记得把[BlogRoot]\_config.yml
里的配置项给注释或者删除掉。
方案二:进阶版(多模型 + 自定义交互)
基于OhMyLive2D
组件,支持多模型切换、自定义提示语和交互菜单,兼容 Cubism2~5 全版本模型。
模型资源:oh-my-live2d/live2d-models: 为OhMyLive2D提供的高质量模型仓库
详情请看:kongxiangyiren/hexo-oh-my-live2d: 一个用于 hexo 的 live2d 看板娘插件,支持所有版本的模型。
特点
-
纯 JS 实现,无需额外依赖
-
支持多模型配置、移动端适配
-
可自定义提示语、菜单按钮(如添加 GitHub 跳转)
安装步骤
-
安装插件
在 Hexo 根目录执行:
bash
npm install hexo-oh-my-live2d
- 配置站点配置文件
在[BlogRoot]\_config.yml
中添加以下配置(按需调整):
yaml
# hexo-oh-my-live2d 配置
OhMyLive2d:
enable: true
CDN: https://unpkg.com/oh-my-live2d
option:
dockedPosition: 'right' # 模型停靠位置 默认值: 'right' 可选值: 'left' | 'right'
# menus: |
# (currentModel) =>{
# console.log(currentModel);
# }
# menus:
# items: |
# (defaultItems)=>{
# return [
# ...defaultItems,
# {
# id: 'github',
# icon: 'github-fill',
# title: '我的github',
# onClick: ()=>window.open('https://github.com/hacxy')
# }
# ]
# }
# items:
# - id: 'github'
# icon: 'github-fill'
# title: '我的github'
# onClick: ()=>window.open('https://github.com/hacxy')
mobileDisplay: true # 是否在移动端显示
models:
- path: https://unpkg.com/live2d-widget-model-shizuku@1.0.5/assets/shizuku.model.json
mobilePosition: [-10, 23] # 移动端时模型在舞台中的位置。 默认值: [0,0] [横坐标, 纵坐标]
mobileScale: 0.1 # 移动端时模型的缩放比例 默认值: 0.1
mobileStageStyle: # 移动端时舞台的样式
width: 180
height: 166
motionPreloadStrategy: IDLE # 动作预加载策略 默认值: IDLE 可选值: ALL | IDLE | NONE
position: [-10, 35] # 模型在舞台中的位置。 默认值: [0,0] [横坐标, 纵坐标]
scale: 0.15 # 模型的缩放比例 默认值: 0.1
# showHitAreaFrames: false # 是否显示点击区域 默认值: false
stageStyle:
width: 250
height: 250
- path: 'https://unpkg.com/live2d-widget-model-koharu@1.0.5/assets/koharu.model.json'
scale: 0.12
position: [0, 0]
stageStyle:
width: 250
mobileScale: 0.08
mobilePosition: [0, 0]
mobileStageStyle: # 移动端时舞台的样式
width: 180
parentElement: document.body #为组件提供一个父元素,如果未指定则默认挂载到 body 中
primaryColor: 'var(--btn-bg)' # 主题色 支持变量
sayHello: false # 是否在初始化阶段打印项目信息
tips:
style:
width: 230
height: 120
left: calc(50% - 20px)
top: -100px
mobileStyle:
width: 180
height: 80
left: calc(50% - 30px)
top: -100px
idleTips:
interval: 15000
# message:
# - 你好呀~
# - 欢迎来到我的小站~
# 自定义提示语 需要 引入 axios 库 ,也可以使用其他方法
message: |
function(){
return axios.get('https://v1.hitokoto.cn?c=i')
.then(function (response) {
return response.data.hitokoto ;
})
.catch(function (error) {
console.error(error);
});
}
# wordTheDay: true
# 自定义 https://v1.hitokoto.cn 数据
# wordTheDay: |
# function(wordTheDayData){
# return `${wordTheDayData.hitokoto} by.${wordTheDayData.from}`;
# }
# 具体方法请看: https://oml2d.com/guide/loadModel.html#oml2d-%E5%AE%9E%E4%BE%8B
# then: |
# oml2d.onStageSlideIn(() => {
# oml2d.tipsMessage('Oh My Live2D !!!', 3000, 10);
# });
- 生效配置
执行hexo cl && hexo g && hexo s
,访问本地服务即可查看多模型切换效果。
更多配置参考 OhMyLive2D 官方文档
效果如图:

方案三:完全版(高度自定义功能)
基于stevenjoezhang/live2d-widget
库,支持模型切换、换装、互动动作等高级功能,适合追求个性化的用户。
安装步骤
-
下载资源
进入 Butterfly 主题的 source 目录,克隆仓库:
bash
cd themes/butterfly/source/
git clone https://github.com/stevenjoezhang/live2d-widget.git live2d-widget
- 修改本地路径
打开themes/butterfly/source/live2d-widget/dist/autoload.js
,将资源路径改为本地:
js
// 注释原CDN路径,替换为本地路径
// const live2d_path = 'https://fastly.jsdelivr.net/npm/live2d-widgets@1.0.0-rc.6/dist/';
const live2d_path = '/live2d-widget/dist/';
- 注入主题
打开[BlogRoot]\_config.butterfly.yml
(主题配置文件),在inject
中添加脚本:
yaml
# 插入代码到头部 </head> 之前 和 底部 </body> 之前
inject:
head:
- <script src="/live2d-widget/dist/autoload.js"></script>
bottom:
注意事项
-
若本地正常显示但部署后不生效,可能是缓存问题,执行
hexo cl
清除缓存即可。 -
移动端显示异常时,检查配置中
mobile: show: true
(方案一)或mobileDisplay: true
(方案二)是否启用。 -
本地正常,线上不显示或部分显示?可能是资源被 GFW 拦截,建议替换为国内 CDN。当然,不在乎也行。比如,博客在移动端部分效果或图标不能显示,"魔法上网" 就正常了。
-
两个都装的话,效果图如下,方案一在右边,方案三在左边:

参考资料
- Live2D Cubism | イラストに命が宿る感動を - 描かれた「絵」そのものを自在に動かす表現技術。
- EYHN/hexo-helper-live2d: Add the Sseexxyyy live2d to your hexo!
- 博客魔改教程总结(一) | Fomalhaut🥝
- Hexo博客搭建系列(三):在Hexo博客中配置Live2D看板娘教程-CSDN博客
- 给butterfly主题添加看板娘live2d | 天涯路远
- stevenjoezhang/live2d-widget: 把萌萌哒的看板娘抱回家 (ノ≧∇≦)ノ | Live2D widget for web platform
- 在网页中添加 Live2D 看板娘 | 米米的博客
- Peter🥝 - A blog about technology and life
- 为博客添加 Live2D 看板娘折腾的那些事 - 博客