前置说明

Butterfly 5.7 已移除内置的 aplayerInject 支持，所以需要手动注入 APlayer 资源，用独立 JS 文件控制

第一步：放入音乐文件

在 source 目录 创建 music 文件夹，把 mp3 放进去，文件名建议用简单的中文 / 英文，避免日文、空格、特殊符号，单首歌建议 <10MB

1
2
3
4
source/music/
├── song1.mp3
├── song2.mp3
└── song3.mp3

第二步：主题配置 _config.butterfly.yml

2.1 开启 PJAX（切页音乐不断），找到 pjax: 改为：

1
2
pjax:
  enable: true

2.2 在 inject.head 中添加 CSS，找到 inject: → head:，在末尾添加：

1
2
3
4
5
6
7
8
inject:
  head:
    # ... 你原有的其他配置 ...
    
    # APlayer 音乐播放器 CSS
    - <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.css">
    # 侧边固定播放器样式（默认隐藏，点击按钮滑出）
    - <style>#global-aplayer{position:fixed;right:-300px;top:50%;transform:translateY(-50%);width:280px;z-index:999;box-shadow:0 2px 12px rgba(0,0,0,.25);border-radius:8px 0 0 8px;overflow:hidden;transition:right .3s ease}#global-aplayer.show{right:0}#global-aplayer .aplayer{margin:0;border-radius:0}#aplayer-toggle{position:fixed;right:0;top:50%;transform:translateY(-50%);width:34px;height:76px;background:#49b1f5;color:#fff;display:flex;align-items:center;justify-content:center;border-radius:8px 0 0 8px;cursor:pointer;z-index:998;font-size:16px;box-shadow:-2px 0 8px rgba(0,0,0,.2);transition:right .3s ease;user-select:none}#aplayer-toggle:hover{background:#3a9fd9}#aplayer-toggle.hide{right:280px}@media(max-width:768px){#global-aplayer{width:220px}#aplayer-toggle.hide{right:220px}}</style>

2.3 在 inject.bottom 中添加 JS 和容器，找到 inject: → bottom:，在末尾添加：

1
2
3
4
5
6
7
8
9
10
11
bottom:
  # ... 你原有的其他配置 ...
  
  # APlayer 音乐播放器 JS
  - <script src="https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.js"></script>
  # 全局侧边播放器容器（在 PJAX 区域外，切页不销毁）
  - <div id="global-aplayer"></div>
  # 播放器切换按钮（点击滑出/收起）
  - <div id="aplayer-toggle" title="音乐播放器">♪</div>
  # 引入独立的播放器配置 JS
  - <script src="/js/music-player.js"></script>

第三步：创建独立的 JS 配置文件

新建文件：source/js/music-player.js，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
/* ============================================
 * 侧边音乐播放器配置
 * 修改歌曲名/歌手/文件路径只需改下面的 musicList 数组
 * ============================================ */

// 歌曲列表 —— 以后加歌/改歌名只改这里
var musicList = [
  {
    name: '歌曲名1',
    artist: '歌手1',
    url: '/music/song1.mp3',
    cover: '/img/music-cover.jpg'
  },
  {
    name: '歌曲名2',
    artist: '歌手2',
    url: '/music/song2.mp3',
    cover: '/img/music-cover.jpg'
  },
  {
    name: '歌曲名3',
    artist: '歌手3',
    url: '/music/song3.mp3',
    cover: '/img/music-cover.jpg'
  }
  // 加歌格式：
  // ,{
  //   name: '歌曲名',
  //   artist: '歌手',
  //   url: '/music/文件名.mp3',
  //   cover: '/img/封面.jpg'
  // }
];

// 对 URL 进行编码，处理中文/特殊字符，避免音频加载失败
musicList.forEach(function (song) {
  if (song.url) song.url = encodeURI(song.url);
});

// 播放器配置 —— 一般不用改
var playerConfig = {
  theme: '#49b1f5',    // 主题色
  loop: 'all',         // 循环模式：all / one / none
  order: 'random',     // 播放顺序：list 顺序 / random 随机
  volume: 0.8          // 默认音量 0~1
};

// 初始化播放器
function initMusicPlayer() {
  if (typeof APlayer === 'undefined' || window.globalAplayer) return;

  var el = document.getElementById('global-aplayer');
  if (!el) return;

  window.globalAplayer = new APlayer(Object.assign({
    container: el,
    audio: musicList,
    preload: 'auto'  // 页面打开即缓冲音频
  }, playerConfig));

  // 创建"点击播放音乐"提示
  var tip = document.createElement('div');
  tip.id = 'music-play-tip';
  tip.innerHTML = '🎵 点击播放音乐';
  tip.style.cssText = 'position:fixed;right:40px;bottom:30px;background:#49b1f5;color:#fff;padding:10px 18px;border-radius:20px;font-size:14px;cursor:pointer;z-index:9999;box-shadow:0 2px 10px rgba(0,0,0,.2);animation:musicTipBounce 1.5s ease-in-out infinite;';
  var style = document.createElement('style');
  style.textContent = '@keyframes musicTipBounce{0%,100%{transform:translateY(0)}50%{transform:translateY(-6px)}}';
  document.head.appendChild(style);
  document.body.appendChild(tip);

  // 自动播放：用户首次点击/触摸/按键后立即播放（浏览器策略要求）
  var autoPlayed = false;
  function autoPlay() {
    if (autoPlayed) return;
    autoPlayed = true;
    window.globalAplayer.play();
    if (tip && tip.parentNode) tip.parentNode.removeChild(tip);
    document.removeEventListener('click', autoPlay);
    document.removeEventListener('touchstart', autoPlay);
    document.removeEventListener('keydown', autoPlay);
  }
  document.addEventListener('click', autoPlay);
  document.addEventListener('touchstart', autoPlay);
  document.addEventListener('keydown', autoPlay);
  if (tip) tip.addEventListener('click', autoPlay);

  // 切换按钮：点击滑出/收起
  var toggle = document.getElementById('aplayer-toggle');
  if (toggle) {
    toggle.addEventListener('click', function () {
      el.classList.toggle('show');
      toggle.classList.toggle('hide');
    });
  }
}

// DOM 已就绪就直接初始化，否则等 DOMContentLoaded
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', initMusicPlayer);
} else {
  initMusicPlayer();
}

第四步：（可选）放入封面图片

把封面图片放到：

1
source/img/music-cover.jpg

没有也没关系，播放器会显示默认占位图

第五步：构建测试

1
hexo clean && hexo g && hexo s

打开 http://localhost:4000：
页面右侧中间有一个蓝色 ♪ 按钮
右下角有跳动的 🎵 点击播放音乐 提示
点击页面任意位置，音乐自动播放，提示消失
点击 ♪ 按钮，播放器从右侧滑出

日常维护

操作 改哪里
加歌 / 改歌名 source/js/music-player.js 的 musicList 数组
改音量 / 主题色 source/js/music-player.js 的 playerConfig
换音乐文件 替换 source/music/ 里的 mp3
改播放器宽度 / 位置 _config.butterfly.yml 的 inject.head 里的 CSS

注意事项

1，自动播放限制：浏览器禁止有声音的自动播放，必须用户点击页面后才会出声，这是所有网站都面临的限制
2，文件名：建议用简单的中文 / 英文名，避免日文、空格、特殊符号
3，文件大小：单首歌建议 <10MB，太大就压缩一下
4，PJAX：必须开启，否则切换页面音乐会中断
5，播放器容器位置：必须在 inject.bottom 中（PJAX 区域外），否则切页会被销毁
6，url 必须和 source/music/ 里的文件名完全一致（包括大小写、后缀）
7，name 和 artist 自己填，想显示什么就填什么
8，cover 可以都用同一张封面图，也可以每首歌单独配
9，加完后运行 hexo clean && hexo s 生效

在这里插入图片描述