音乐播放器

本页说明全局音乐播放器的歌单配置、加载策略、播放模式与界面形态，并列出常见问题的排查方法。

网站内置全局音乐播放器，由三部分协作完成：

板块	文件	职责
状态管理	src/context/MusicContext.jsx	歌单、播放状态、进度、音量、播放模式
悬浮迷你条	src/components/MusicPlayerWidget.jsx	页面右下角的常驻紧凑卡片（仅 2xl 超宽屏显示）
弹出卡片	src/components/MusicPlayerCard.jsx	导航栏音乐按钮弹出的紧凑播放卡片

歌单配置

在 content.config.js 的 playlist 中配置歌单：

export const playlist = [
  {
    id: 1,                             // 唯一 id，从 1 开始顺延
    title: '刻晴赋',                    // 歌名
    artist: '夏翊然',                   // 艺术家名
    src: '/music/keqing-fu.mp3',       // 音频文件路径（文件放 public/music/）
    cover: '/images/music-cover.jpg',  // 封面图路径（文件放 public/images/）
  },
];

各字段的说明如下表所示：

字段	说明
id	歌曲唯一标识，不要重复
title	歌名
artist	艺术家名
src	音频文件路径。文件必须放在 public/music/ 目录
cover	封面图，显示在迷你条和展开卡片上

添加歌曲：放入音频文件后，在数组末尾追加一项即可，无需修改任何代码。歌单为空数组时，播放器在所有位置自动隐藏。

功能特性

懒加载音频（重要）

音频实例（<audio> 元素）在首次点击播放时才创建，且 preload = 'none'。

这意味着首页不会预先下载体积动辄十几 MB 的 MP3，首屏加载速度不受音乐文件影响。

播放模式

MusicContext 中实现了三种模式的切换逻辑（playMode：0 列表循环 / 1 单曲循环 / 2 随机），默认列表循环：播完自动切下一首，到末尾回到第一首。

注意

切换逻辑已在状态层就绪，但当前播放器卡片上没有渲染模式切换按钮，模式固定为列表循环。如需开放切换，请在 MusicPlayerCard.jsx 中添加一个调用 setPlayMode 的按钮。

音量记忆

音量调节后写入 localStorage（键 keqing-volume，范围 0~1 自动钳制），下次访问自动恢复上次音量。

全局持续播放

播放器挂在 App.jsx 路由外层，切换 / ↔ /contributors 页面不会中断播放。

双入口（均为紧凑卡片）

• 导航栏音乐按钮：点击弹出紧凑卡片（歌单非空时显示；2xl 超宽屏下隐藏，由悬浮条接管）
• 页面角落悬浮条 MusicPlayerWidget：固定在右下角的紧凑卡片，仅 2xl 超宽屏显示，不可点击展开

界面细节

播放器实际渲染的是紧凑形态（MusicPlayerCard compact），包含：封面、歌名 + 艺术家、上一首 / 播放暂停 / 下一首。

MusicPlayerCard.jsx 中另有一个完整版卡片（大封面、可点击跳转的进度条、时间、音量条、封面右下角的律动可视化条），但当前代码中没有任何位置渲染它。如需启用，在任意组件中直接渲染 <MusicPlayerCard />（不传 compact）即可；律动条可在 theme.config.js → effects.animations.musicVisualizer 中关闭或调整参数。

常见问题

为什么手机浏览器无法自动播放

浏览器策略禁止带声音的自动播放，属于正常行为。本网站未提供自动播放，用户点击播放按钮即可。

点击播放没有声音或无响应

• 检查 playlist 中 src 路径与实际文件名完全一致（大小写敏感，Linux 服务器上 A.mp3 ≠ a.mp3）
• 确认文件确实位于 public/music/ 下（不是 src/）
• 按 F12 打开开发者工具，在 Network 面板检查音频请求是否返回 404

如何移除播放器

删除 src/App.jsx 中的 <MusicPlayerWidget /> 一行（导航栏按钮在 Navbar.jsx 中，另有条件渲染）。保留歌单配置不会产生任何显示。