Hexo Butterfly 博客添加音乐功能完全指南

为个人博客添加背景音乐，能在阅读时营造氛围，也让站点更有辨识度。在 Hexo + Butterfly 生态里，常见做法有两类：一是用 hexo-tag-aplayer 插件在文章中插入播放器；二是直接利用 Butterfly 主题内置的 APlayer / MetingJS 注入能力，更轻量、也更适合全局吸底播放。本文整合官方插件文档与 Butterfly 全局吸底教程，按步骤说明两种方案的安装与配置。

方法一：使用 hexo-tag-aplayer 插件

hexo-tag-aplayer 是 APlayer 的 Hexo 标签插件，支持单曲、歌词、本地播放列表，以及通过 MetingJS 调用网易云、QQ 音乐等平台歌单。

步骤 1：安装插件

在博客根目录执行：

npm install --save hexo-tag-aplayer

安装完成后执行 hexo clean，再重新生成站点。

步骤 2：在博文中嵌入音乐

单曲

{% aplayer "曲目标题" "作者" "音乐文件URL" "封面图URL" %}

带更多参数时，建议为每个参数加双引号（Hexo 标签参数中不宜直接含空格）：

{% aplayer "Caffeine" "Jeff Williams" "caffeine.mp3" "picture.jpg" "autoplay" "width:70%" "lrc:caffeine.txt" %}

参数	说明
title	曲目标题
author	作者
url	音乐文件地址
picture_url	（可选）封面图
narrow	（可选）袖珍模式
autoplay	（可选）自动播放（移动端多数浏览器不支持）
width:xxx	（可选）宽度，默认 100%
lrc:xxx	（可选）歌词文件 URL

若开启了 文章资源文件夹，可将 mp3、封面、歌词放在与文章同名的目录中，直接写相对路径引用。

带歌词（内联 LRC）

{% aplayerlrc "title" "author" "url" "autoplay" %}
[00:00.00]lrc here
{% endaplayerlrc %}

播放列表（JSON）

{% aplayerlist %}
{
    "narrow": false,
    "autoplay": false,
    "mode": "random",
    "showlrc": 3,
    "mutex": true,
    "theme": "#e6d0b2",
    "preload": "metadata",
    "listmaxheight": "513px",
    "music": [
        {
            "title": "CoCo",
            "author": "Jeff Williams",
            "url": "caffeine.mp3",
            "pic": "caffeine.jpeg",
            "lrc": "caffeine.txt"
        },
        {
            "title": "アイロニ",
            "author": "鹿乃",
            "url": "irony.mp3",
            "pic": "irony.jpg"
        }
    ]
}
{% endaplayerlist %}

常用 JSON 字段说明：

字段	说明
mode	播放模式：random（随机）、single（单曲循环）、circulation（列表循环，默认）、order（顺序播放）
theme	主题色，默认 #b7daff
mutex	为 true 时，同页其他 APlayer 播放会暂停当前播放器
preload	预加载：none / metadata / auto
listmaxheight	播放列表最大高度
showlrc	歌词显示方式，可选 1 / 2 / 3

使用 MetingJS 标签（在线歌单）

在站点根目录 _config.yml 中开启 Meting 支持：

aplayer:
  meting: true

文章中可写：

{% meting "60198" "netease" "playlist" %}

{% meting "60198" "netease" "playlist" "autoplay" "mutex:false" "listmaxheight:340px" "preload:none" "theme:#ad7a86" %}

⚠️ 重要：避免重复加载脚本

hexo-tag-aplayer 默认会通过过滤器向页面注入 APlayer.js 与 Meting.js。Butterfly 主题也会注入同类资源，两者同时开启 asset_inject 时容易重复加载，导致播放器异常。

在站点 _config.yml 中关闭插件的自动注入，改由主题统一加载：

aplayer:
  meting: true
  asset_inject: false

若仍出现脚本冲突，可检查主题是否已开启 aplayerInject（见方法二），并确保全站只保留一套 APlayer / Meting 资源。

---

方法二：使用 Butterfly 主题内置能力（更推荐）

Butterfly 已集成 APlayer 与 MetingJS，无需安装 hexo-tag-aplayer 即可在 Markdown 中写 HTML 标签，或通过 inject.bottom 配置全局吸底播放器。配置更简单，也更适合全站常驻音乐。

步骤 1：开启主题资源注入

编辑 _config.butterfly.yml（若你使用 theme: butterfly，修改的是博客根目录下该文件，而非 themes/butterfly/_config.yml）：

aplayerInject:
  enable: true
  per_page: true

• enable: true：注入 APlayer / Meting 的 CSS 与 JS。
• per_page: true：在需要的页面加载（配合全局吸底时建议开启）。

同时建议在站点 _config.yml 中配合：

aplayer:
  meting: true
  asset_inject: false

这样即使用过 hexo-tag-aplayer，也不会与主题重复注入脚本。

步骤 2：在文章中插入音乐

在 Markdown 正文中直接写 HTML（MetingJS 写法），无需 {% %} 标签：

<div class="aplayer"
     data-id="60198"
     data-server="netease"
     data-type="playlist"
     data-autoplay="false"
     data-theme="#ad7a86">
</div>

将 data-id 换成目标歌曲 / 歌单 / 专辑 ID，data-server 与 data-type 与平台一致即可。本地 mp3 也可通过 APlayer 原生配置实现，但在线歌单以 Meting 最省事。

步骤 3：配置全局吸底播放器

若希望全站左下角固定迷你播放器，且切换页面时音乐不中断，需完成以下三点。

1. 吸底与迷你模式

在播放器容器上设置：

• data-fixed="true"：固定吸底模式。
• data-mini="true"：迷你样式（推荐与吸底搭配）。

2. PJAX 与 no-destroy

Butterfly 默认开启 PJAX。页面切换时，普通 APlayer 实例可能被销毁。在 class 中加入 **no-destroy**，主题会保留固定播放器实例：

<div class="aplayer no-destroy"
     data-id="60198"
     data-server="netease"
     data-type="playlist"
     data-fixed="true"
     data-mini="true"
     data-autoplay="false"
     data-order="random"
     data-preload="none"
     data-theme="#e6d0b2">
</div>

确保 _config.butterfly.yml 中 pjax.enable 为 true（Butterfly 吸底教程中亦强调：希望切页不断歌时需开启 PJAX）。

3. 写入 inject.bottom

将完整 HTML 一行写入主题配置的 inject.bottom，例如：

inject:
  head:
  bottom:
    - <div class="aplayer no-destroy" data-id="60198" data-server="netease" data-type="playlist" data-fixed="true" data-mini="true" data-listFolded="false" data-order="random" data-preload="none" data-autoplay="false" data-theme="#e6d0b2"></div>

保存后执行 hexo clean && hexo g，部署或本地 hexo s 预览。

data-* 参数说明（MetingJS）

属性	默认值	说明
data-id	必填	歌曲 ID、歌单 ID、专辑 ID 或搜索关键词
data-server	必填	音乐平台，见下表
data-type	必填	song / playlist / album / search / artist
data-fixed	false	是否固定吸底
data-mini	false	是否迷你模式
data-autoplay	false	是否自动播放（移动端常受限）
data-theme	#2980b9	主题色
data-loop	all	循环：all / one / none
data-order	list	播放顺序：list / random
data-volume	0.7	默认音量（用户手动调节后会被记住）
data-mutex	true	为 true 时，同页其他播放器播放会暂停本播放器
data-lrctype	0	歌词类型
data-listFolded	false	播放列表是否默认折叠
data-listmaxheight	340px	列表最大高度
data-preload	auto	预加载：none / metadata / auto
data-storagename	metingjs	LocalStorage 存储配置的键名

主流平台 data-server 取值：

平台	data-server
网易云音乐	netease
QQ 音乐	tencent
虾米音乐	xiami
酷狗音乐	kugou
百度音乐	baidu

歌单 ID 需在对应平台获取（如网易云歌单页 URL 中的数字 ID）。若某平台接口失效，可更换 data-server 或换用本地 mp3 + 插件 {% aplayerlist %} 方案。

---

故障排除与进阶提示

1. 部署后没有播放器

   • 逐项核对：aplayerInject.enable、asset_inject: false、是否执行了 hexo clean。
   • 检查浏览器控制台是否有 404（CDN 或 Meting API 被墙/失效）。
   • 尝试更换 data-id 或音乐源（netease ↔ tencent 等）。

2. 重复加载或播放器闪退

   • 确认仅一处开启脚本注入（主题 或 插件 asset_inject: true，不要同时为 true）。
   • 全站吸底务必加 no-destroy，并设置 data-fixed="true"。

3. PJAX 页面单曲播放器异常

   • 非吸底、仅文章内播放器时，可参考 hexo-tag-aplayer 文档，在 pjax:start 时手动 destroy() 全局 window.aplayers（Butterfly 主题对非 fixed 实例已做类似处理）。

4. 标签参数含空格

   • {% aplayer %} / {% meting %} 的参数请用英文双引号包裹。

5. 进阶

   • 可在 aplayer-custom.js 中用 APlayer 原生 API 配置本地歌单（适合版权清晰、可自托管的 mp3）。
   • 自建 Meting API 可缓解公共接口不稳定问题，在 _config.yml 的 aplayer.meting_api 中配置。

---

总结

对比项	hexo-tag-aplayer（方法一）	Butterfly 内置（方法二）
安装	需 npm install 插件	仅需改主题配置
适用场景	单篇文章、本地列表、复杂 {% meting %} 标签	全站吸底、Markdown 内嵌 HTML
配置重点	标签语法 + asset_inject: false	aplayerInject + inject.bottom + no-destroy
灵活度	标签丰富，适合重度定制	更轻量，与主题 PJAX 配合更好

• 只想在某几篇文章里放歌、或大量使用本地文件 / JSON 列表：优先考虑 hexo-tag-aplayer，并关闭 asset_inject。
• 想要全站左下角常驻、切页不断歌：优先 Butterfly 内置方案，按本文方法二配置即可。

按你的需求二选一或组合使用（全站用方法二，个别文章用方法一），注意始终避免重复注入 APlayer / Meting 脚本。配置完成后记得 hexo clean && hexo g 再部署，祝你的博客早日响起喜欢的 BGM。

---

参考文档

• hexo-tag-aplayer 中文说明
• Butterfly 添加全局吸底 Aplayer 教程