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])打开终端,执行以下命令安装插件:

bash 复制代码
npm install --save hexo-helper-live2d
  1. 配置站点配置文件

    打开[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 # 移动端显示
  1. 生效配置

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

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

更换模型

  1. 安装新模型(以shizuku为例):
bash 复制代码
npm install --save live2d-widget-model-shizuku
  1. 修改_config.ymlmodel.use为新模型名称:
yaml 复制代码
model:
  use: live2d-widget-model-shizuku # 替换为新模型名
  # 默认为live2d-widget-model-wanko
  1. 重新执行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 跳转)

安装步骤

  1. 安装插件

    在 Hexo 根目录执行:

bash 复制代码
npm install hexo-oh-my-live2d
  1. 配置站点配置文件

[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);
  #    });
  1. 生效配置

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

更多配置参考 OhMyLive2D 官方文档

效果如图:

方案三:完全版(高度自定义功能)

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

安装步骤

  1. 下载资源

    进入 Butterfly 主题的 source 目录,克隆仓库:

bash 复制代码
cd themes/butterfly/source/
git clone https://github.com/stevenjoezhang/live2d-widget.git live2d-widget
  1. 修改本地路径

打开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/';
  1. 注入主题

打开[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。当然,不在乎也行。比如,博客在移动端部分效果或图标不能显示,"魔法上网" 就正常了。

  • 两个都装的话,效果图如下,方案一在右边,方案三在左边:


参考资料

相关推荐
ajsbxi6 小时前
【Java 基础】核心知识点梳理
java·开发语言·笔记
呱呱巨基7 小时前
vim编辑器
linux·笔记·学习·编辑器·vim
新子y7 小时前
【小白笔记】普通二叉树(General Binary Tree)和二叉搜索树的最近公共祖先(LCA)
开发语言·笔记·python
聪明的笨猪猪7 小时前
Java JVM “调优” 面试清单(含超通俗生活案例与深度理解)
java·经验分享·笔记·面试
爱学习的uu7 小时前
CURSOR最新使用指南及使用思路
人工智能·笔记·python·软件工程
YuCaiH7 小时前
Linux文件处理
linux·笔记·嵌入式
Cathy Bryant7 小时前
大模型损失函数(二):KL散度(Kullback-Leibler divergence)
笔记·神经网络·机器学习·数学建模·transformer
qq_398586548 小时前
Threejs入门学习笔记
javascript·笔记·学习
hour_go8 小时前
TCP/IP协议相关知识点
网络·笔记·网络协议·tcp/ip