Hexo Butterfly 集成 Mineradio 粒子音乐播放器

hexo-mineradio 是基于开源项目 Mineradio 二次开发的纯前端音乐播放器，适配 Hexo 博客。安装插件并填写网易云音乐歌单 ID 后，Hexo 会自动生成完整的播放器页面和静态资源。

本站效果：八音盒

一、安装播放器

进入 Hexo 博客根目录，安装已发布的 npm 包：

1
npm install hexo-mineradio@latest

插件要求 Hexo 6 或更高版本、Node.js 16 或更高版本。安装后不需要复制播放器目录，也不需要配置 skip_render、修改播放器源码或维护歌单 JSON 文件。

二、配置网易云歌单

在 Hexo 根目录的 _config.yml 末尾加入：

1
2
mineradio:
  playlist_id: "你的网易云音乐歌单ID"

enable、播放器路径、返回地址、浏览器缓存和站点集成都有可直接使用的默认值，因此无需全部复制。安装 1.0.5 或更高版本后，包还会自动注入全屏容器、返回逻辑、播放器预加载和首次点击播放优化，不需要在主题中额外引入 JS 或 CSS。

主要配置项如下：

配置项 默认值 说明
enable true 是否生成播放器页面
route relaxation/music 播放器访问路径，不要在开头添加 /
playlist_id 空 默认网易云音乐歌单 ID
playlist_ids [] 需要同时载入的其他歌单 ID
meting_endpoint https://api.i-meto.com/meting/api 获取歌单、歌曲和歌词的接口
return_url auto 左上角返回地址；auto 会使用 Hexo 的站点根路径
site_integration true 是否自动启用无刷新全屏打开和播放器状态保留
player_preload true 是否在页面空闲时预加载播放器和当前歌曲
browser_cache true 是否在浏览器中缓存最近一次成功载入的歌单

需要载入多个歌单时，可以这样填写：

1
2
3
4
5
6
mineradio:
  enable: true
  playlist_id: "默认歌单ID"
  playlist_ids:
    - "其他歌单ID一"
    - "其他歌单ID二"

获取歌单 ID

  1. 在网易云音乐网页或客户端中打开公开歌单。
  2. 选择分享并复制链接。
  3. 找到链接中 id= 后面的数字，将它填写到 playlist_id。

例如链接为：

1
https://music.163.com/#/playlist?id=123456789

对应的歌单 ID 就是 123456789。歌单需要允许公开访问，否则前端接口无法读取。

三、添加 Butterfly 菜单入口

播放器会生成独立的全屏页面。在 _config.butterfly.yml 的 menu 中增加入口即可：

1
2
3
4
menu:
  首页: / || icon-home || faa-tada
  休闲 || icon-pinweishenghuo || faa-tada || hide:
    八音盒: /relaxation/music/ || icon-yinle || faa-tada

如果修改了 route，这里的链接也要使用相同路径。包会自动接管这个站内链接，在全屏容器中打开播放器；从播放器返回时，原页面和音乐状态都会保留。无需手工创建 iframe，也无需在 Butterfly 的 inject 中添加播放器脚本。

从旧版本升级

升级到 1.0.5 或更高版本后，如果博客以前手工配置过类似功能，请删除以下内容，避免事件重复注册：

  • _config.butterfly.yml 中手工添加的播放器导航脚本。
  • source/js 中自行维护的播放器导航或首次播放补丁。
  • 主题自定义 CSS 中的 #mineradio-shell、#mineradio-frame 和 body.mineradio-shell-open 样式。

删除后重新执行 npm install 和 Hexo 清理生成即可。

四、生成并验证

重新生成站点：

1
2
npx hexo clean
npx hexo generate

生成成功后应存在：

1
public/relaxation/music/index.html

启动本地预览：

1
npx hexo server

浏览器打开：

1
http://localhost:4000/relaxation/music/

确认以下功能正常：

  • 页面能够直接进入 Mineradio，不显示 Butterfly 的文章容器。
  • 歌单可以载入，点击歌曲后可以播放。
  • 在歌单仍在加载时点击播放，资源就绪后能够自动开始，不需要点击第二次。
  • 从其他页面进入和返回时，页面与播放器资源不会重复加载。
  • 封面和歌词能够随歌曲更新。
  • 视觉设置、歌单架和底部控制栏可以正常打开和关闭。
  • 刷新页面后没有播放器资源 404 或未处理的控制台异常。
常见问题

页面显示 404

确认 hexo-mineradio 已写入博客的 dependencies，检查 _config.yml 的 YAML 缩进，然后重新执行 npx hexo clean 和 npx hexo generate。不需要额外配置 skip_render。

歌单载入失败

检查歌单 ID 是否正确、歌单是否公开，以及当前网络是否能访问配置的 meting_endpoint。如果使用镜像站或 CDN，还要确认它没有拦截跨域请求。

有封面但无法播放

歌曲可能存在版权或会员限制，音频地址也可能已经过期。刷新页面可以重新请求歌单资源，但纯前端播放器不能绕过平台限制。

移动端不能自动播放

这是浏览器的自动播放策略。用户首次进入页面后仍需要主动点击一次播放按钮；如果歌单尚未载入，这次点击会被保留，资源就绪后自动播放，不需要再次点击。

说明

播放器数据来自浏览器能够访问的公开接口，不需要自行部署数据库或音乐服务端。分发和修改播放器时，请遵守 GPL-3.0 许可证，并保留包内的 LICENSE、NOTICE.md 和原项目署名；歌曲、封面和歌词的使用还应遵守对应平台规则。

参考资料