本站左下角那枚竖着的音乐胶囊,看起来像插件做的,实际上没有用 APlayer、MetingJS,也没有用任何“音乐插件”。它就是一个原生 <audio> 标签、一份歌曲数组、一个固定在左下角的 div,再加一点 CSS。

这篇教程按“我连音乐插件是什么都不知道”的起点写。你不需要装任何 npm 包,跟着做就能得到一个能播放、能显示歌词、能切歌、鼠标悬停会展开按钮的音乐胶囊。

核心思路只有一句话:全站只保留一个 <audio>,胶囊只是它的一个“遥控器 + 显示屏”。

文章第 2~4 节已经把三个文件的完整代码摆出来了,喜欢复制的话直接复制即可。下载链接放在文章最后。

阅读路线

你想做什么 看哪一节
我只想先把胶囊跑起来 第 1~5 节
我想知道为什么不用插件 第 0、7 节
我想接 QQ 音乐 / 网易云 第 8 节
我想翻页音乐不断 第 9 节
我手机上打不开 / 自动播放失败 第 10 节
我照做了但没反应 第 11 节
我只想直接下载文件 第 13 节

第 0 步:先搞清楚“音乐插件”和“音乐胶囊”不是一回事

很多教程会让你装:

  • APlayer
  • MetingJS
  • hexo-tag-aplayer
  • 某个音乐解析插件

它们能快速生成一个播放器,但有几个问题:

  1. 样式是插件的,想改成“竖排胶囊”要覆盖一堆你不懂的选择器;
  2. 插件通常自己创建一个 <audio>,你再加一个胶囊,就会出现两个播放器各放各的;
  3. pjax 换页后,插件实例可能被销毁;
  4. 移动端、歌词、自动播放限制都得围着插件的规则转。

本站的做法是把这些全拆开:

角色 谁负责
真正发声 一个原生 <audio>
歌曲队列 / 播放状态 自己写的 music-bus.js
左下角胶囊 UI 自己写的 music-capsule.js
外观 自己写的 music-capsule.css
第三方音乐接口 可选,服务端代理;新手阶段完全不需要

音乐胶囊结构:一个 audio 单例与多个界面

中间的 music-bus.js 是唯一播放核心;左下角胶囊、侧栏面板和 /music/ 页面都只是它的“遥控器 + 显示屏”。

所以这篇教程不装插件。你只需要会复制三个文件、改一处配置。


第 1 步:准备几首能公开播放的音频

最稳妥的方式,是准备几个你自己能控制的 .mp3 文件,例如:

1
2
3
source/music/01.mp3
source/music/02.mp3
source/music/03.mp3

Hexo 会把 source/ 下的内容原样发布,所以生成后地址就是:

1
2
3
/music/01.mp3
/music/02.mp3
/music/03.mp3

音频地址必须是 HTTPS,或者本地 localhost。如果你的站点是 HTTPS,而音频是 http://...,浏览器会拦截混合内容,表现就是“按钮点了没声音”。

如果你暂时没有自己的 mp3,也可以用公开可直链的测试音频,但不要依赖别人的热链做正式站,对方一改地址你就全挂了。


第 2 步:写播放核心 music-bus.js

新建:

1
source/js/music-bus.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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
/* music-bus.js —— 全站唯一播放核心 */
(function (global) {
'use strict';

var audio = null;
var queue = [];
var idx = -1;
var subs = [];
var playing = false;
var lines = [];
var lineIndex = -1;
var errCount = 0;

function emit(type, data) {
for (var i = 0; i < subs.length; i++) {
try { subs[i](type, data || {}); } catch (e) { }
}
}

function on(fn) {
if (typeof fn === 'function' && subs.indexOf(fn) < 0) subs.push(fn);
return fn;
}

function parseLrc(text) {
var out = [];
String(text || '').split(/\r?\n/).forEach(function (line) {
var stamps = line.match(/\[\d{1,3}:\d{1,2}(?:[.:]\d{1,3})?\]/g);
if (!stamps) return;
var body = line.replace(/\[[^\]]*\]/g, '').trim();
if (!body) return;
stamps.forEach(function (s) {
var m = s.match(/\[(\d{1,3}):(\d{1,2})(?:[.:](\d{1,3}))?\]/);
if (!m) return;
var frac = m[3] ? parseFloat('0.' + m[3]) : 0;
out.push({
t: parseInt(m[1], 10) * 60 + parseInt(m[2], 10) + frac,
text: body
});
});
});
return out.sort(function (a, b) { return a.t - b.t; });
}

function snapshot() {
return {
index: idx,
track: idx >= 0 ? queue[idx] : null,
playing: playing,
cur: audio ? (audio.currentTime || 0) : 0,
dur: audio && isFinite(audio.duration) ? audio.duration : 0,
lines: lines,
lineIndex: lineIndex
};
}

function attach() {
if (audio) return audio;

audio = document.createElement('audio');
audio.preload = 'metadata';
audio.volume = 0.8;
audio.style.display = 'none';
document.body.appendChild(audio);

audio.addEventListener('playing', function () {
playing = true;
errCount = 0;
emit('state', snapshot());
});

audio.addEventListener('pause', function () {
playing = false;
emit('state', snapshot());
});

audio.addEventListener('timeupdate', onTime);
audio.addEventListener('loadedmetadata', onTime);

audio.addEventListener('ended', function () {
playIndex(idx + 1);
});

audio.addEventListener('error', function () {
emit('error', { track: queue[idx] || null });
errCount++;
if (errCount >= 3) {
emit('blocked', { message: '连续 3 首都播不了,先检查音频地址' });
return;
}
playIndex(idx + 1, true);
});

return audio;
}

function onTime() {
if (!audio) return;

var t = audio.currentTime || 0;
var found = -1;
for (var i = 0; i < lines.length; i++) {
if (lines[i].t <= t + 0.2) found = i; else break;
}

if (found !== lineIndex) {
lineIndex = found;
emit('line', {
index: found,
text: found >= 0 ? lines[found].text : ''
});
}

emit('time', snapshot());
}

function setQueue(list) {
queue = Array.isArray(list) ? list : [];
idx = -1;
lines = [];
lineIndex = -1;
emit('queue', { list: queue });
}

function playIndex(i, fromError) {
if (!queue.length) return;
if (!fromError) errCount = 0;

idx = ((i % queue.length) + queue.length) % queue.length;
var item = queue[idx];
var a = attach();

lines = parseLrc(item.lrc || '');
lineIndex = -1;

a.src = item.url;
a.load();
emit('track', snapshot());

var p = a.play();
if (p && p.catch) {
p.catch(function () {
emit('blocked', { message: '浏览器拦了自动播放,请点一下播放键' });
});
}
}

function toggle() {
if (idx < 0) {
playIndex(0);
return;
}

var a = attach();
if (a.paused) {
var p = a.play();
if (p && p.catch) {
p.catch(function () {
emit('blocked', { message: '浏览器拦了自动播放,请再点一次' });
});
}
} else {
a.pause();
}
}

function next() {
playIndex(idx + 1);
}

function prev() {
if (audio && audio.currentTime > 3) {
audio.currentTime = 0;
return;
}
playIndex(idx - 1);
}

global.MiniPlayer = {
on: on,
setQueue: setQueue,
playIndex: playIndex,
toggle: toggle,
next: next,
prev: prev,
state: snapshot,
parseLrc: parseLrc
};
})(window);

这段代码做了几件事:

  1. 只创建一个 <audio>;
  2. 提供一个 queue 数组;
  3. 对外暴露 toggle / next / prev / playIndex;
  4. 通过 on() 把播放状态广播给胶囊 UI;
  5. 能解析最简单的 LRC 歌词。

如果你只想要“歌名歌词”,不想做歌词,也可以把 lrc 字段留空。胶囊会退化成显示歌名。


第 3 步:写胶囊 UI music-capsule.js

新建:

1
source/js/music-capsule.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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
/* music-capsule.js —— 左下角竖排音乐胶囊 */
(function () {
'use strict';

/* ① 你的歌单
url 必填;name / artist / cover / lrc 可选。
lrc 可以是 LRC 文本;这里为了简单,演示一行一行写。 */
var PLAYLIST = [
{
name: '示例歌曲一',
artist: '示例歌手',
url: '/music/01.mp3',
lrc: '[0:00] 正在播放\n[0:05] 这里是第一句歌词\n[0:10] 这里是第二句歌词'
},
{
name: '示例歌曲二',
artist: '示例歌手',
url: '/music/02.mp3',
lrc: '[0:00] 第二首歌\n[0:06] 歌词照样能显示'
},
{
name: '示例歌曲三',
artist: '示例歌手',
url: '/music/03.mp3'
}
];

var ICON = {
music: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 3v9.28a4.39 4.39 0 1 0 2 3.7V6h4V3h-6z"/></svg>',
play: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z"/></svg>',
pause: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M7 5h4v14H7zm6 0h4v14h-4z"/></svg>',
prev: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 6h2v12H6zm3.5 6 8.5 6V6z"/></svg>',
next: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M16 6h2v12h-2zM6 6l8.5 6L6 18z"/></svg>'
};

var el = null;
var cur = null;
var playBtn = null;

function ensure() {
if (el && el.isConnected) return;

el = document.createElement('div');
el.id = 'mini-music';
el.setAttribute('role', 'group');
el.setAttribute('aria-label', '音乐播放器');
el.innerHTML =
'<div class="mm-main">' +
'<div class="mm-top">' + ICON.music + '</div>' +
'<div class="mm-text"><span class="mm-cur">点播放键开始</span></div>' +
'</div>' +
'<div class="mm-keys">' +
'<button type="button" class="mm-side" data-act="prev" title="上一首">' + ICON.prev + '</button>' +
'<button type="button" class="mm-play" data-act="play" title="播放 / 暂停">' + ICON.play + '</button>' +
'<button type="button" class="mm-side" data-act="next" title="下一首">' + ICON.next + '</button>' +
'</div>';

document.body.appendChild(el);

cur = el.querySelector('.mm-cur');
playBtn = el.querySelector('.mm-play');

el.addEventListener('click', function (e) {
var btn = e.target.closest ? e.target.closest('[data-act]') : null;
if (!btn) return;
var act = btn.getAttribute('data-act');
if (act === 'play') window.MiniPlayer.toggle();
else if (act === 'next') window.MiniPlayer.next();
else if (act === 'prev') window.MiniPlayer.prev();
});

var s = window.MiniPlayer.state();
if (s.track) applyTrack(s);
}

function setText(text) {
if (cur) cur.textContent = text || '音乐播放中';
}

function applyTrack(s) {
if (!el || !s.track) return;
el.classList.add('is-on');
setText(s.track.name + (s.track.artist ? ' - ' + s.track.artist : ''));
}

function applyState(s) {
if (!el) return;
el.classList.toggle('is-playing', !!s.playing);
el.classList.toggle('is-paused', !s.playing);
if (playBtn) playBtn.innerHTML = s.playing ? ICON.pause : ICON.play;
}

function init() {
if (!window.MiniPlayer) return;

window.MiniPlayer.setQueue(PLAYLIST);

window.MiniPlayer.on(function (type, data) {
if (type === 'track') applyTrack(data);
else if (type === 'state') applyState(data);
else if (type === 'line' && data.text) setText(data.text);
else if (type === 'blocked') setText(data.message || '请点一下播放键');
else if (type === 'error') setText('这首歌播不了,已跳下一首');
});

ensure();

/* pjax 换页后若容器被替换,补建一次;已存在则什么都不做 */
document.addEventListener('pjax:complete', ensure);
}

if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', init);
} else {
init();
}
})();

这里有几个新手容易疑惑的点:

  • e.target.closest() 用来判断你点的是不是按钮,不用给每个按钮单独绑事件;
  • is-on 控制胶囊显示,没歌曲时不占地方;
  • line 事件来了就显示歌词,没歌词就一直显示歌名;
  • pjax:complete 再跑一次 ensure(),是为了翻页后补建被换掉的 DOM。

第 4 步:写胶囊样式 music-capsule.css

新建:

1
source/css/music-capsule.css

复制下面这段:

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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
/* 左下角竖排音乐胶囊 */
:root {
--mm-glass: rgba(255, 255, 255, .94);
--mm-ink: #1f2937;
--mm-dim: rgba(31, 41, 55, .62);
--mm-bd: rgba(169, 169, 169, .55);
--mm-accent: var(--theme-color, #ff1493);
--mm-on: #fff;
--mm-chip: rgba(0, 0, 0, .07);
}

[data-theme="dark"] {
--mm-glass: rgba(18, 22, 28, .92);
--mm-ink: rgba(255, 255, 255, .9);
--mm-dim: rgba(255, 255, 255, .55);
--mm-bd: rgba(255, 255, 255, .16);
--mm-chip: rgba(255, 255, 255, .1);
}

#mini-music {
--mm-col: 52px;
--mm-keys: 46px;

position: fixed;
left: calc(10px + env(safe-area-inset-left, 0px));
bottom: calc(72px + env(safe-area-inset-bottom, 0px));
z-index: 1001;
box-sizing: border-box;
display: flex;
flex-direction: row;
align-items: stretch;
width: var(--mm-col);
max-width: var(--mm-col);
min-height: 170px;
max-height: min(72vh, 460px);
padding: 10px 0 9px;
overflow: hidden;
border: 1px solid var(--mm-bd);
border-radius: 999px;
background: var(--mm-glass);
box-shadow: 0 2px 10px rgba(7, 17, 27, .1);
color: var(--mm-ink);
font-size: 12.5px;
line-height: 1;

visibility: hidden;
opacity: 0;
transform: translateY(6px) scale(.96);
transform-origin: 0 100%;
pointer-events: none;
transition: opacity .24s ease, transform .24s ease, visibility .24s,
width .24s ease, max-width .24s ease;
}

#mini-music.is-on {
visibility: visible;
opacity: 1;
transform: none;
pointer-events: auto;
}

/* 鼠标悬停 / 键盘聚焦:从 52px 加宽到 98px,露出右侧按钮 */
#mini-music:hover,
#mini-music:focus-within {
width: calc(var(--mm-col) + var(--mm-keys));
max-width: calc(var(--mm-col) + var(--mm-keys));
}

#mini-music .mm-main {
flex: 0 0 var(--mm-col);
width: var(--mm-col);
display: flex;
flex-direction: column;
align-items: center;
}

#mini-music .mm-top {
flex: 0 0 22px;
width: 100%;
display: grid;
place-items: center;
}

#mini-music .mm-top svg {
width: 16px;
height: 16px;
fill: var(--mm-accent);
opacity: .92;
}

#mini-music .mm-text {
flex: 1 1 auto;
min-height: 0;
width: 100%;
display: flex;
align-items: center;
justify-content: center;
overflow: hidden;

/* 竖排:中文书脊方向;英文侧躺 90 度 */
writing-mode: vertical-rl;
text-orientation: mixed;
white-space: nowrap;
text-align: center;
line-height: 1.35;
letter-spacing: .3px;
}

#mini-music .mm-keys {
flex: 0 0 var(--mm-keys);
width: var(--mm-keys);
display: flex;
flex-direction: column;
align-items: center;
justify-content: space-around;
gap: 6px;
}

#mini-music button {
padding: 0;
border: 0;
border-radius: 50%;
display: grid;
place-items: center;
cursor: pointer;
-webkit-tap-highlight-color: transparent;
transition: opacity .18s ease, background .18s ease, transform .18s ease;
}

#mini-music button svg {
display: block;
width: 18px;
height: 18px;
fill: currentColor;
}

#mini-music .mm-side {
width: 30px;
height: 30px;
background: transparent;
color: var(--mm-ink);
opacity: 0;
pointer-events: none;
}

#mini-music .mm-play {
width: 34px;
height: 34px;
background: var(--mm-accent);
color: var(--mm-on);
opacity: 0;
pointer-events: none;
transform: scale(.86);
}

#mini-music:hover .mm-side,
#mini-music:focus-within .mm-side,
#mini-music:hover .mm-play,
#mini-music:focus-within .mm-play {
opacity: 1;
pointer-events: auto;
transform: scale(1);
}

#mini-music .mm-side:hover {
background: var(--mm-chip);
transform: scale(1.06);
}

#mini-music .mm-play:hover {
transform: scale(1.08);
filter: brightness(1.08);
}

#mini-music .mm-side:focus-visible,
#mini-music .mm-play:focus-visible {
outline: 2px solid var(--mm-accent);
outline-offset: 2px;
}

#mini-music.is-paused .mm-text {
color: var(--mm-dim);
}

@media (max-width: 600px) {
#mini-music {
--mm-col: 48px;
--mm-keys: 42px;
bottom: calc(68px + env(safe-area-inset-bottom, 0px));
width: 48px;
max-width: 48px;
padding: 7px 0;
font-size: 12px;
min-height: 158px;
}
}

/* 触屏设备没有真正的 hover:按钮常显,胶囊直接展开,否则手机上点不到播放键 */
@media (hover: none) {
#mini-music {
width: calc(var(--mm-col) + var(--mm-keys));
max-width: calc(var(--mm-col) + var(--mm-keys));
}
#mini-music .mm-side,
#mini-music .mm-play {
opacity: 1;
pointer-events: auto;
transform: none;
}
}

@media (prefers-reduced-motion: reduce) {
#mini-music,
#mini-music button {
transition: none;
}
}

这段 CSS 决定了胶囊的“气质”:

  • writing-mode: vertical-rl:歌词竖着排;
  • white-space: nowrap:一句歌词只占一列,不会变成古籍那种多列排版;
  • border-radius: 999px:胶囊形;
  • :hover 才加宽:平时只占 52px,不挡正文;
  • env(safe-area-inset-*):iPhone 底部小黑条不会压住它。

本站的完整版还有侧栏悬停面板、歌曲列表浮层、三处 UI 共用一个播放核心。教程版只保留左下角胶囊,代码少很多,但原理一样。


第 5 步:把三个文件接进 Hexo

先确认你的项目最终长成这样(用 ZIP 的话,解压后把三个文件分别丢进对应目录):

1
2
3
4
5
6
7
8
9
10
11
12
你的博客根目录/
├─ source/
│ ├─ css/
│ │ └─ music-capsule.css
│ ├─ js/
│ │ ├─ music-bus.js
│ │ └─ music-capsule.js
│ └─ music/
│ ├─ 01.mp3
│ ├─ 02.mp3
│ └─ 03.mp3
└─ _config.chengic.yml ← 本教程以 chengic 主题为例

打开主题配置文件,找到 inject.head 和 inject.bottom。

配置文件名字不一定一样:本站叫 _config.chengic.yml;Butterfly 常叫 _config.butterfly.yml;有些主题叫 themes/你的主题/_config.yml。只要找到“注入 head / 注入 footer”的字段即可。

在 inject.head 里加:

1
- <link rel="stylesheet" href="/css/music-capsule.css?v=20261121a">

在 inject.bottom 里加,注意顺序不能反:

1
2
- <script defer src="/js/music-bus.js?v=20261121a"></script>
- <script defer src="/js/music-capsule.js?v=20261121a"></script>

为什么顺序重要?因为 music-capsule.js 一上来就要用 window.MiniPlayer。defer 脚本按书写顺序执行,播放核心必须在前面。

这段是给“全新 Hexo 博客”加的。本站自己的 _config.chengic.yml 里不会出现这三行,因为本站跑的是完整版:music-bus.js?v=20261102-resume5 + music-page.js + daily-say.js,对应全局对象是 window.fomalPlayer。教程里的 ZIP 是精简演示包,用 window.MiniPlayer。不要把演示包再注入本站,否则会出现两个 <audio> 同时抢播放。

然后:

1
2
hexo clean
hexo server

打开:

1
http://localhost:4000/

或者你配置的端口。左下角应该出现一枚竖着的胶囊,鼠标移上去展开三个按钮,点中间的播放键开始放歌。


第 6 步:第一次不响?这是浏览器的正常限制

现代浏览器不允许网页自动播放带声音的媒体。所以:

  • 页面刚打开就自己响:不行;
  • 访客点了一下播放键:可以。

本站代码里也专门处理了这个情况:

1
2
3
4
5
6
var p = a.play();
if (p && p.catch) {
p.catch(function () {
emit('blocked', { message: '浏览器拦了自动播放,请点一下播放键' });
});
}

如果你在控制台看到 play() failed because the user didn't interact with the document first,不是代码错了,是浏览器在保护用户。

不要用“静音自动播放再取消静音”去绕过限制,很多浏览器已经堵了这条路。老老实实让用户点一次播放键。


第 7 步:为什么这套方案不需要音乐插件

插件做的事情,其实就是帮你生成:

1
2
3
<audio src="..."></audio>
<button>播放</button>
<button>下一首</button>

这些东西原生 HTML 都有。我们只是把它们组织得更有条理:

插件方案 本教程方案
插件创建 <audio> 自己 document.createElement('audio')
插件管理队列 自己一个 queue 数组
插件绑定按钮 自己 addEventListener('click')
插件给样式 自己写 CSS
插件处理 pjax 自己监听 pjax:complete

所以你并没有“少用什么能力”,只是把能力拆开自己拿回来了。


第 8 步:进阶——接 QQ 音乐 / 网易云(可选,新手先跳过)

本站正式版接的是 QQ 音乐公开歌单,但不是浏览器直连音乐平台。原因是:

  1. 音乐平台接口有 CORS 限制;
  2. 播放地址经常带有时效签名;
  3. Cookie、referer 这些不能放前端。

本站的结构是:

1
2
3
4
5
浏览器胶囊 / 音乐页
↓
同源服务端代理 /api/music
↓
QQ 音乐公开接口

服务端只提供几个动作:

1
2
3
4
qq_pl     取歌单
qq_url 取播放地址
qq_lyric 取歌词
qq_search 搜索

如果你想接自己的音乐源,推荐顺序:

  1. 先用本地 mp3 把胶囊跑通;
  2. 再写一个同源 /api/music 代理;
  3. 让代理只返回 name/artist/cover/url/lrc 这几个字段;
  4. 前端歌单数组换成接口返回的数据。

播放核心不用改,因为它只认统一后的歌曲对象:

1
2
3
4
5
6
7
{
name: '歌名',
artist: '歌手',
url: 'https://你的同源代理/xxx',
cover: 'https://...',
lrc: '[0:00] ...'
}

第 9 步:翻页音乐不断——pjax 与整页刷新

9.1 pjax 跳页

pjax 只替换页面的一部分,不会销毁整个 <audio>。所以本站的胶囊能在站内跳页时继续播放。

你要保证两件事:

  1. 播放核心脚本不要放在会被 pjax 替换的正文容器里;
  2. 胶囊脚本监听 pjax:complete 补建 DOM。
1
document.addEventListener('pjax:complete', ensure);

如果你的站有“随便逛逛”“相关推荐”这类站内跳转函数
别写:

1
location.href = url;

要写:

1
window.pjax.loadUrl(url);

否则会整页刷新,单例 <audio> 被销毁。

9.2 整页刷新续播

F5、右键“在新标签页打开”、地址栏回车这些操作,pjax 拦不住。本站的做法是:

  • 页面离开前,把“队列 + 第几首 + 第几秒 + 用户是否想播放”写进 sessionStorage;
  • 新页面加载后再读回来,跳到同一秒继续播。

核心字段大致是:

1
2
3
4
5
6
7
{
at: Date.now(), // 快照时间
i: 3, // 第几首
t: 82.5, // 第几秒
p: true, // 用户想不想让它播
q: [/* 瘦身后的队列 */]
}

有两个特别容易踩的坑:

  1. 别存 audio.paused
    页面卸载时浏览器会自己 pause,存实时状态会得到 true,新页面就不续播了。要存“用户意图”。
  2. 快照要瘦身
    sessionStorage 一般只有 5MB,歌词文本别整首塞进去,队列也要限量。

教程版先不做这一步。等你把基础胶囊跑通,再回来加。


第 10 步:手机端与常见限制

10.1 手机端没有 hover

桌面端靠 :hover 展开按钮,手机端没有真正的悬停。本站最后保留了“常驻胶囊”,没有改成“点一下才展开”,因为多点一次才能切歌更麻烦。

教程版 CSS 里手机端只是把胶囊缩到 48px,没有隐藏按钮区域。如果你愿意,也可以点播放键时临时加一个 .is-open 类展开。

10.2 音频和封面都要 HTTPS

站点是 HTTPS 时,下面这些都会失败:

1
2
http://example.com/a.mp3
http://example.com/cover.jpg

浏览器会报混合内容错误。全部换成 HTTPS。

10.3 跨域不是“音频播放”的主要障碍

普通 <audio src="https://..."> 直接播放通常不需要 CORS;但如果你要:

  • 读歌词;
  • 读封面画布;
  • 做频谱;
  • fetch JSON 歌单;

那就需要对方给 CORS 头,或者走同源代理。本站的频谱方案最后没用,就是因为 CDN 不给 Access-Control-Allow-Origin。

10.4 overscroll-behavior: contain 别乱加

在歌词列表上加这个属性,会阻止滚动传给父级,看起来像“页面卡住”。本站踩过这个坑,后来删掉了。


第 11 步:照做了没反应?按这个表查

现象 最可能原因 怎么查
左下角什么都没有 CSS 没注入 / 歌单没设置 / JS 报错 F12 看有没有 #mini-music
有胶囊但点播放没声音 音频地址错 / 混合内容 / 自动播放被拦 控制台 Network 看 mp3 请求
控制台报 MiniPlayer is not defined 两个脚本顺序反了 bus 必须在 capsule 前面
控制台报 play() failed 没有用户手势 让用户点播放键,别自动播
歌词不显示 LRC 格式错 / 时间轴没到 先把 lrc 写成 [0:00] 测试
切歌后还显示上一首歌词 没有在 playIndex 里清空 lines 检查 lines = parseLrc(...)
pjax 翻页后胶囊消失 容器被替换,没有补建 检查 pjax:complete 监听
翻页音乐停了 用了 location.href 整页跳 改成 window.pjax.loadUrl(url)
改了没生效 ?v= 没升版本 换一个版本号并重启 server
手机端挡正文 胶囊太宽 / 高度写死 检查 @media (max-width:600px)

第 12 步:上线前检查清单

  • [ ] 三个文件都在 source/ 对应目录;
  • [ ] CSS 在 inject.head;
  • [ ] JS 在 inject.bottom;
  • [ ] music-bus.js 排在 music-capsule.js 前面;
  • [ ] 音频地址是 HTTPS;
  • [ ] 歌单里至少有一首能直链的 mp3;
  • [ ] 第一次播放由点击触发;
  • [ ] 桌面端悬停能展开按钮;
  • [ ] 手机端胶囊不挡正文;
  • [ ] 深色模式下文字看得清;
  • [ ] pjax 翻页后胶囊还在;
  • [ ] 改过文件后 ?v= 版本号已更新;
  • [ ] hexo clean && hexo generate 通过;
  • [ ] 没有把任何 Cookie、token、私有 API、服务器路径写进公开页面。

第 13 步:下载完整文件包

不想手动复制也没关系,三个文件已经打包好了:

下载后按第 5 节的目录结构放置:

1
2
3
source/js/music-bus.js
source/js/music-capsule.js
source/css/music-capsule.css

文件包里不包含音频,请按第 1 节准备自己的 mp3,并在 music-capsule.js 的 PLAYLIST 里改成你的歌曲路径。


最后说一句

音乐胶囊最难的地方不是“让声音响起来”,而是让全站只有一套状态:一首歌、一个进度、一个播放意图,所有界面都只是它的镜子。

你先把教程版的 52px 胶囊跑起来,再慢慢加面板、歌单、歌词、续播。不要一开始就把 QQ 音乐接口、pjax、BroadcastChannel 全堆上——那是本站踩了二十多次坑之后的形状,不是第一步该长的样子。