起因#

逛到 v-blog.halei0v0.top 时注意到它右侧悬浮工具栏最底下多了一个音符按钮，点开是一个完整的播放面板：封面、曲名、进度条、播放控制、音量、播放列表，全挤在一个 320px 宽的浮层里。

本站的悬浮工具栏已经有五个按钮——回顶部、回主页、随机一篇、显示目录、跳评论区。这一条本来就是放「全局工具」的地方：常驻可见、不占正文宽度、不跟内容抢位置。再塞一个音符进去，比在侧边栏或页面角落另起一块更合拍。

这篇的标题原本写的是「侧边栏音乐播放器卡片」，那是最初的设想。真做下来才发现侧边栏是根 sticky 长条：卡片要跟距离卡、分类、标签抢纵向空间，滚动时还容易被推出视口，而播放器恰恰需要「一直在手边」。位置换成了悬浮工具栏，文章也跟着重写。

一、先摸清参考站是怎么做的#

抓它的归档页 HTML，能看到两个 Svelte 岛：MusicPlayer（面板）和 MusicFabButton（入口按钮），状态集中在一个 musicPlayerStore 里。

这里有个常见误会值得先拆掉：网上的 Fuwari 音乐播放器教程（包括这篇文章最初的版本）大多走 APlayer + MetingJS 那条路，但参考站用的是自研实现。两者差别不小——APlayer 是一整套带皮肤的播放器，塞进一个 320px 的浮层里要先想办法压掉它自带的样式；自研则是一切从零写，但每个像素和每个事件都在自己手里。

在决定照做之前，先实测这条链路到底还活不活着——这一步比什么都重要，因为第三方 API 挂掉是常态：

206 意味着音频直链支持 Range 请求，进度条拖拽、断点续传都成立；* 意味着浏览器能直连，不需要自己再搭一层代理。链路可用，方案成立。

于是本站的取舍是：照参考站的思路自己做，但不引任何播放器库——零新依赖，一个音符按钮、一个面板、一份配置。

二、三个文件，零新依赖#

按本站的惯例，配置一律集中在 config.ts，组件里不写死任何东西：

1
export const musicConfig: MusicConfig = {
2
  enable: true,
3
  mode: "meting", // meting = 走第三方 API；local = 用下面的本地曲目表
4
  metingApi: "https://meting.mysqil.com/api?server=:server&type=:type&id=:id&auth=:auth&r=:r",
5
  id: "14164869977", // 网易云歌单 id：music.163.com 地址里 playlist?id= 后面那串
6
  server: "netease", // netease / tencent / kugou / xiami / baidu
7
  type: "playlist", // playlist / album / song / artist / search
8
  localPlaylist: [],
9
  volume: 0.7, // 初始音量；访客调过之后以 localStorage 为准
10
  autoplay: false, // 自动播放多半会被浏览器拦，被拦后等首次点击补播
11
};

API 模板里的 :server / :type / :id / :auth / :r 是占位符，运行时替换；config.enable 为 false 时，按钮与面板都不渲染，内联脚本也随之不启动——等于整套功能一起关掉。

三、结构：一个按钮、两个视图#

按钮落在工具栏的最底端（跳评论区之下），和参考站的位置一致：

1
{music && (
2
    <div id="music-fab-btn" class="toolbar-btn music-fab"
3
        data-music-config={JSON.stringify(music)}
4
        role="button" tabindex="0" aria-label="打开音乐控制中心" aria-expanded="false">
5
        <span class="music-fab__icon">
6
            <Icon name="material-symbols:music-note-rounded" class="music-fab__note" />
7
            <span class="music-fab__spinner" aria-hidden="true"></span>
8
        </span>
9
        <span class="music-fab__dot" aria-hidden="true"></span>
10
    </div>
11
)}

面板内部是两个互斥的视图——播放视图和播放列表视图，同一时刻只显示一个。这一点和参考站不同，第四节会说明原因。

图标切换没有一行 JS：脚本只在面板根节点上改 data-* 属性，显示哪个图标交给 CSS：

1
/* 播放态：暂停图标 ↔ 播放图标 */
2
.music-panel[data-playing="1"] .mf-when-paused  { display: none; }
3
.music-panel[data-playing="1"] .mf-when-playing { display: block; }
4

5
/* 循环模式：关 / 列表 / 单曲，三个图标按 data-repeat 切换 */
6
.music-panel[data-repeat="1"] .mf-repeat-list,
7
.music-panel[data-repeat="2"] .mf-repeat-one { display: none; }
8

9
/* 音量：高 / 低 / 静音，按 data-vol 切换 */
10
.music-panel[data-vol="off"] .mf-vol-high,
11
.music-panel[data-vol="off"] .mf-vol-low { display: none; }

这样做的好处是状态与外观彻底解耦：脚本里只需要 panel.setAttribute('data-vol', 'off')，不必记着去哪几个地方换 <Icon>。

四、六个坑#

1
<!-- 内联脚本读这个属性，浏览器会自动解码实体 -->
2
<div id="music-fab-btn" data-music-config={JSON.stringify(music)} ...>

1
function positionPanel() {
2
    var panel = $('music-panel');
3
    var btn = $('music-fab-btn');
4
    var anchor = btn && btn.getBoundingClientRect();
5
    // 按钮缺失或未布局（rect 全 0）时回退到整条工具栏
6
    if (!anchor || !anchor.width || !anchor.bottom) anchor = bar.getBoundingClientRect();
7

8
    var gap = 12;
9
    var w = panel.offsetWidth || 320;
10

11
    // 水平：面板右边缘落在按钮左侧 gap 处；左侧不够就贴视口左边 8px
12
    panel.style.left = Math.max(8, anchor.left - gap - w) + 'px';
13
    panel.style.right = 'auto';
14
    // 垂直：面板底边与按钮底边齐平
15
    panel.style.bottom = Math.max(8, window.innerHeight - anchor.bottom) + 'px';
16
    // 高度：上限是按钮底边以上的空间，超出时面板内部滚动
17
    panel.style.maxHeight = Math.max(220, anchor.bottom - gap * 2) + 'px';
18
}

1
/* 列表项由脚本 innerHTML 生成，元素上没有 Astro 的 scope 属性 */
2
:global(#music-list .music-item) {
3
    display: flex;
4
    align-items: center;
5
    gap: 0.6rem;
6
    padding: 0.45rem 0.5rem;
7
    border-radius: 0.5rem;
8
    cursor: pointer;
9
}
10
:global(#music-list .music-item.is-active) {
11
    background: var(--btn-regular-bg);
12
}

1
function esc(s) {
2
    return String(s == null ? '' : s)
3
        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
4
        .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
5
}

五、音频为什么挂在 window 上、还不进 DOM#

这是整套实现里最容易做错、又最不容易发现的一处。

BackToTop.astro 整体在 Swup 容器之外，所以切页时工具栏本身不会被替换——音乐不会因为换页而中断。但内联脚本会随着新页面重新执行，于是：

1
// 单例：脚本每次重跑都拿同一个 audio，不会被重建
2
var audio = window.__musicFabAudio || (window.__musicFabAudio = new Audio());

如果写成模块级的 var audio = new Audio()，切页时脚本重跑会新建一个 Audio，旧的那个还挂在内存里继续出声——症状是「切了几页之后开始有回音」。挂在 window 上则始终是同一个实例。

另外，这个 audio 不插入 DOM。new Audio() 本身就是 HTMLAudioElement，不挂到文档里也能播；插进 DOM 反而会跟着容器一起被 Swup 替换掉，音乐就断了。

六、和参考站的三处不同#

七、想改就改这几处#

• 换歌单：只改 musicConfig.id（以及 server / type）。
• 换成自己的音频：把 mode 改成 "local"，按 MusicTrack 的字段往 localPlaylist 里填曲目，音频和封面放进 public/。这条路径完全不依赖第三方 API。
• 换 Meting 服务：改 metingApi 模板即可，占位符保持原样。
• 不要这个功能：musicConfig.enable 设为 false，按钮、面板、内联脚本一起消失。

结语#

比起装一个播放器库再想办法把它压进 320px 的浮层，这种「自己写一个单例」的路子反而更省事：没有额外依赖、没有要覆盖的皮肤、每个交互都在自己手里。代价是那些琐碎的细节——属性注入、定位参照物、样式隔离、转义、单例——都得自己过一遍。

也正因为如此，那个「面板底边离屏幕底 576px」的表格才值得记下来：不是算错了，而是参照物选错了。

参考与致谢#

• 参考实现：v-blog.halei0v0.top 的悬浮工具栏音乐播放器
• 数据服务：Meting API（第三方代理，随时可能失效）