为 Butterfly 主题添加音乐页面和全局吸底 APlayer 播放器

适配 MetingJS v2.0.2 版本

修改 aplayer.pug

将[blogroot]/themes/butterfly/layout/includes/third-party中aplayer.pug文件的内容整体替换为

//- MetingJS v2.0.2 适配
link(rel='stylesheet' href=url_for(theme.asset.aplayer_css) media="print" onload="this.media='all'")
script(src=url_for(theme.asset.aplayer_js))
script(src=url_for(theme.asset.meting_js))

// 兼容 hexo-tag-aplayer 插件的 MetingTag
script.
  document.addEventListener('DOMContentLoaded', () => {
    document.querySelectorAll('div.meting-tag-marker').forEach(div => {
      const meting = document.createElement('meting-js');

      ['id', 'server', 'type', 'autoplay', 'mutex', 'listmaxheight', 
       'preload', 'theme', 'fixed', 'mini', 'loop', 'order', 'volume',
       'lrctype', 'listfolded', 'storagename', 'mode'].forEach(attr => {
        const value = div.dataset[attr];
        if (value !== undefined) meting.setAttribute(attr, value);
      });

      div.parentNode.replaceChild(meting, div);
    });
  });

if theme.pjax.enable
  script.
    (() => {
      const destroyAplayer = () => {
        document.querySelectorAll('meting-js').forEach(el => {
          //- 只保留 fixed 播放器，其他的让 disconnectedCallback 处理
          if (el.aplayer && !el.aplayer.options.fixed) {
            el.aplayer.destroy()
            el._initialized = false
          }
        })
      }

      const runMetingJS = () => {
        //- Pjax 后的新元素会自动触发 connectedCallback
        //- 如果状态不一致（已初始化但实例丢失），重置并重新初始化
        document.querySelectorAll('meting-js').forEach(el => {
          if (el._initialized && !el.aplayer) {
            el._initialized = false
            el.connectedCallback()
          }
        })
      }

      btf.addGlobalFn('pjaxSend', destroyAplayer, 'destroyAplayer')
      btf.addGlobalFn('pjaxComplete', runMetingJS, 'runMetingJS')
    })()

修改 plugins.yml

在[blogroot]/themes/butterfly中plugins.yml找到对应内容，如下：

• 修改前

meting_js:
  name: butterfly-extsrc
  file: metingjs/dist/Meting.min.js
  version: 1.1.6

• 修改后

meting_js:
  name: meting
  file: dist/Meting.min.js
  version: 2.0.2

hexo-tag-aplayer 插件的安装和配置

安装插件

执行命令

npm install hexo-tag-aplayer

配置插件

在 Hexo 的配置文件_config.yml中添加如下内容

aplayer:
  meting: true
  asset_inject: false

将主题的配置文件_config.butterfly.yml进行如下修改，开启主题的 aplayerInject

# Inject the css and script (aplayer/meting)
aplayerInject:
  enable: true
  per_page: true

添加音乐页面

效果预览

执行命令

hexo new page music

运行后会在[blogroot]\source\下生成music文件夹，打开music文件夹下的index.md文件，按照如下格式修改内容

---
title: 音乐
date: 2025-11-30 10:52:20
aside: false
aplayer: true
---
{% meting "7419903487" "netease" "playlist" "autoplay" "mutex:true" "listmaxheight:1000px" "preload:auto" "theme:#ad7a86"%}

有关 {% meting %} 的参数说明，见如下列表

选项	默认值	描述
id	必须值	歌曲 id / 播放列表 id / 相册 id / 搜索关键字
server	必须值	音乐平台: netease(网易云音乐), tencent(QQ音乐), kugou(酷狗音乐), xiami(虾米音乐), baidu(百度音乐)
type	必须值	song(歌曲), playlist(歌单), album(专辑), search(搜索关键字), artist(歌手)
fixed	false	开启固定模式
mini	false	开启迷你模式
loop	all	列表循环模式：all, one,none
order	list	列表播放模式： list, random
volume	0.7	播放器音量
lrctype	0	歌词格式类型
listfolded	false	指定音乐播放列表是否折叠
storagename	metingjs	LocalStorage 中存储播放器设定的键名
autoplay	true	自动播放，移动端浏览器暂时不支持此功能
mutex	true	该选项开启时，如果同页面有其他 aplayer 播放，该播放器会暂停
listmaxheight	340px	播放列表的最大长度
preload	auto	音乐文件预载入模式，可选项： none, metadata, auto
theme	#ad7a86	播放器风格色彩设置

不要包含VIP音乐，VIP音乐不能被正常播放

建议使用网易云音乐

查询自己歌单的 id 号

打开网页版网易云后，打开自己要使用的歌单

通过歌单的链接：https://music.163.com/#/my/m/music/playlist?id=7419903487，就能知道歌单的id号了

将页面添加到导航栏

修改主题的配置文件_config.butterfly.yml中的 menu，在menu中添加音乐: /music/ || fas fa-music

menu:
  # 首页: / || fas fa-home
  # 列表||fas fa-list:
  #   音乐: /music/ || fas fa-music
  #   电影: /movies/ || fas fa-video
  音乐: /music/ || fas fa-music

添加吸底 APlayer 播放器

效果预览

如果在音乐页面上也保留吸底 Aplayer 播放器，直接跳转到添加全局吸底 APlayer 播放器

为了不在音乐页面上加载吸底 APlayer 播放器，在[blogroot]\themes\butterfly\scripts\下新建文件aplayer.js并粘贴如下代码

/* themes/butterfly/scripts/aplayer.js */
hexo.extend.filter.register("after_render:html", function (html, data) {
  const urlObj = new URL(data.url); // 把绝对 URL 转成 URL 对象
  const path = urlObj.pathname; // 去除域名，提取路径部分
  if (path.startsWith("/music/")) return html; // 如果路径以 /music/ 开头，直接返回原 HTML，不添加播放器

  const aplayer = `
    <meting-js
      api="https://meting.o0w0b.top/api?server=netease&type=playlist&id=7419903487"
      fixed="true"
      mini="true"
      autoplay="true">
    </meting-js>
  `;
  return html.replace("</body>", aplayer + "\n</body>");
});

有关meting-js的参数说明，见如下列表

参数	默认值	说明
id	必填	歌曲 ID / 歌单 ID / 专辑 ID / 搜索关键词
server	必填	音乐平台：netease、tencent、kugou、xiami、baidu
type	必填	song（歌曲）、playlist（歌单）、album（专辑）、search（搜索）、artist（艺术家）
auto	可选	音乐链接，支持：netease、tencent、xiami
api	可选	自定义 API 地址，支持自建 Meting API
fixed	false	启用固定模式
mini	false	启用迷你模式
autoplay	false	音频自动播放
theme	#2980b9	主题主颜色
loop	all	播放器循环模式，可选值：all、one、none
order	list	播放顺序，可选值：list（列表顺序）、random（随机）
preload	auto	预加载模式，可选值：none、metadata、auto
volume	0.7	默认音量。播放器会记住用户设置，因此用户修改过音量后，该默认值将不再生效
mutex	true	防止多个播放器同时播放，当当前播放器开始播放时会暂停其他播放器
lrc-type	0	歌词类型
list-folded	false	是否默认折叠播放列表
list-max-height	340px	播放列表最大高度
storage-name	metingjs	用于存储播放器设置的 localStorage 键名

APlayer 的完整参数可参考：https://aplayer.js.org/#/zh-Hans/?id=%E5%8F%82%E6%95%B0

fixed（吸底）和 mini （最小化）也必须配置，配置为 true

PJAX 是一种网页技术，用于实现“局部页面刷新”，可以让网站在用户点击链接时只加载页面改变的部分，而不是整个网页重新加载，从而提高网页访问速度和用户体验

为了在切换页面时，音乐不会中断，把主题配置文件_config.butterfly.yml中的 pjax修改为true

并且排除在刚刚添加的音乐页面不使用pjax

# https://github.com/MoOx/pjax
pjax:
  # 是否启用 pjax
  enable: true
  # 排除指定页面不使用 pjax，如 '/music/'
  exclude:
    # - /xxxxxx/
    - /music/

由于 after_render:html 钩子不会在 PJAX 局部跳转时重新执行，由于音乐页面未加载吸底 APlayer 播放器，后续跳转到其他页面时将缺失吸底 APlayer 播放器

只要从音乐页面跳转时触发整页刷新，让浏览器重新请求完整 HTML，吸底 APlayer 播放器就能正常初始化并显示

在[blogroot]\themes\butterfly\layout\includes\additional-js.pug内容的最下方粘贴如下代码

script.
  (function () {
    // 拦截任何后续点击
    document.addEventListener('click', function (e) {
      var link = e.target.closest('a');
      if (!link) return;
      if (e.ctrlKey || e.metaKey || e.shiftKey || e.button === 1) return; // 忽略新标签/中键
      if (link.origin !== location.origin) return;                       // 只处理同域
      var fromMusic = location.pathname.startsWith('/music/');
      var toMusic   = link.pathname.startsWith('/music/');
      if (fromMusic && !toMusic) {        // 真正离开 music
        e.preventDefault();
        window.location.href = link.href; // 强制整页刷新
      }
    });
  })();

这样就添加好了

添加全局吸底 APlayer 播放器

把aplayer代码插入到主题配置文件_config.butterfly.yml的inject.bottom中

inject:
  head:
  bottom:
    - <meting-js api="https://meting.o0w0b.top/api?server=netease&type=playlist&id=7419903487"
      fixed="true"
      mini="true"
      autoplay="true">
      </meting-js>

有关meting-js的参数说明，点击此处查看

PJAX 是一种网页技术，用于实现“局部页面刷新”，可以让网站在用户点击链接时只加载页面改变的部分，而不是整个网页重新加载，从而提高网页访问速度和用户体验

为了在切换页面时，音乐不会中断，把主题配置文件_config.butterfly.yml中的 pjax修改为true

# https://github.com/MoOx/pjax
pjax:
  # 是否启用 pjax
  enable: true
  # 排除指定页面不使用 pjax，如 '/music/'
  exclude:
    # - /xxxxxx/

这样就添加好了

More info

🍭 Such a beautiful HTML5 music player

DIYgod/APlayer

🍰 A powerful plugin connect APlayer and Meting

metowolf/MetingJS

Embed aplayer in Hexo posts/pages

MoePlayer/hexo-tag-aplayer