Hexo + Butterfly 博客添加 Live2D 看板娘指南

---

前言

在个人博客中加入 Live2D 看板娘，能让静态页面瞬间充满活力，提升访客互动感。本文整理了三种在 Hexo+Butterfly 主题中添加 Live2D 看板娘的方案，从快速部署到高度自定义，适合不同需求的开发者。

什么是 Live2D？

Live2D 是一种将 2D 插画转化为动态互动形象的技术，通过骨骼绑定和动画逻辑，让平面图像实现类似 3D 的立体动态效果。其官方 SDK 名为 Cubism，目前主要有 2/3/4/5 版本（不同版本支持的模型格式不同，例如 Cubism5 不支持 Cubism2 模型）。

方案一：简单版（快速部署单一模型）

适合新手入门，基于hexo-helper-live2d插件实现，步骤简单，单一模型展示。

安装步骤

1. 安装核心插件

   在 Hexo 根目录（[BlogRoot]）打开终端，执行以下命令安装插件：

npm install --save hexo-helper-live2d

2. 配置站点配置文件

   打开[BlogRoot]\_config.yml（站点配置文件），在底部添加或修改以下配置（按注释调整参数）：

# 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 # 你的自定义 urltagMode: 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 # 你的自定义 urldisplay:position: right # 显示位置（left/right）width: 150 # 看板娘宽度height: 300 # 高度mobile:show: true # 移动端显示

3. 生效配置

   执行以下命令重新生成页面，访问localhost:4000即可查看效果。

hexo cl && hexo g && hexo s  # 清除缓存 -> 生成静态文件 -> 启动本地服务

更换模型

1. 安装新模型（以shizuku为例）：

npm install --save live2d-widget-model-shizuku

2. 修改_config.yml中model.use为新模型名称：

model:use: live2d-widget-model-shizuku # 替换为新模型名# 默认为live2d-widget-model-wanko

3. 重新执行hexo cl && hexo g && hexo s生效。

卸载方法

# 卸载插件
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 跳转）

安装步骤

1. 安装插件

   在 Hexo 根目录执行：

npm install hexo-oh-my-live2d

2. 配置站点配置文件

在[BlogRoot]\_config.yml中添加以下配置（按需调整）：

# hexo-oh-my-live2d 配置
OhMyLive2d:enable: trueCDN: https://unpkg.com/oh-my-live2doption: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.jsonmobilePosition: [-10, 23] # 移动端时模型在舞台中的位置。 默认值: [0,0] [横坐标, 纵坐标]mobileScale: 0.1 # 移动端时模型的缩放比例 默认值: 0.1mobileStageStyle: # 移动端时舞台的样式width: 180height: 166motionPreloadStrategy: IDLE # 动作预加载策略 默认值: IDLE 可选值: ALL | IDLE | NONEposition: [-10, 35] # 模型在舞台中的位置。 默认值: [0,0] [横坐标, 纵坐标]scale: 0.15 # 模型的缩放比例 默认值: 0.1# showHitAreaFrames: false # 是否显示点击区域 默认值: falsestageStyle:width: 250height: 250- path: 'https://unpkg.com/live2d-widget-model-koharu@1.0.5/assets/koharu.model.json'scale: 0.12position: [0, 0]stageStyle:width: 250mobileScale: 0.08mobilePosition: [0, 0]mobileStageStyle: # 移动端时舞台的样式width: 180parentElement: document.body #为组件提供一个父元素，如果未指定则默认挂载到 body 中primaryColor: 'var(--btn-bg)' # 主题色 支持变量sayHello: false # 是否在初始化阶段打印项目信息tips:style:width: 230height: 120left: calc(50% - 20px)top: -100pxmobileStyle:width: 180height: 80left: calc(50% - 30px)top: -100pxidleTips: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);#    });

3. 生效配置

执行hexo cl && hexo g && hexo s，访问本地服务即可查看多模型切换效果。

更多配置参考 OhMyLive2D 官方文档

效果如图：

方案三：完全版（高度自定义功能）

基于stevenjoezhang/live2d-widget库，支持模型切换、换装、互动动作等高级功能，适合追求个性化的用户。

安装步骤

1. 下载资源

   进入 Butterfly 主题的 source 目录，克隆仓库：

cd themes/butterfly/source/
git clone https://github.com/stevenjoezhang/live2d-widget.git live2d-widget

2. 修改本地路径

打开themes/butterfly/source/live2d-widget/dist/autoload.js，将资源路径改为本地：

// 注释原CDN路径，替换为本地路径
// const live2d_path = 'https://fastly.jsdelivr.net/npm/live2d-widgets@1.0.0-rc.6/dist/';
const live2d_path = '/live2d-widget/dist/';

3. 注入主题

打开[BlogRoot]\_config.butterfly.yml（主题配置文件），在inject中添加脚本：

# 插入代码到头部 </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 看板娘折腾的那些事 - 博客