音乐页面搭建指南

什么是 Meting API#

Meting 是一个开源的音乐聚合 API，支持网易云音乐、QQ 音乐、酷狗等平台。无需服务器，使用公共 API 即可获取歌曲信息、音频链接和歌词。

配置步骤#

1. 选择音乐平台

1
meting: {
2
    server: "netease",  // netease=网易云, tencent=QQ, kugou=酷狗
3
}

2. 选择获取类型

1
meting: {
2
    type: "playlist",  // song=单曲, playlist=歌单, album=专辑, artist=艺术家
3
}

3. 填入 ID

• 歌单 ID：打开网易云歌单页面，URL 中的数字就是 ID
• 专辑 ID：同理
• 单曲 ID：歌曲页面 URL 中的数字

示例 — 网易云歌单 https://music.163.com/#/playlist?id=10046455237，ID 为 10046455237

1
meting: {
2
    server: "netease",
3
    type: "playlist",
4
    id: "10046455237",
5
}

4. 配置备用 API（推荐）

公共 API 可能不稳定，配置多个 fallback：

1
meting: {
2
    api: "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
3
    fallbackApis: [
4
        "https://api.injahow.cn/meting/?server=:server&type=:type&id=:id",
5
        "https://api.moeyao.cn/meting/?server=:server&type=:type&id=:id",
6
    ],
7
}

工作流程：主 API 失败 → 依次尝试 fallback → 全部失败 → 自动回退到本地播放列表

常用公共 Meting API#

第一步：准备文件#

在 public/assets/music/ 目录下放置音频文件：

1
public/
2
└── assets/
3
    └── music/
4
        ├── 歌曲1.mp3
5
        ├── 歌曲1.lrc
6
        ├── 歌曲2.m4a
7
        ├── cover/
8
        │   ├── 封面1.jpg
9
        │   └── 封面2.jpg

支持格式：MP3、M4A、OGG、WAV

快速获取文件： 使用 python scripts/download_music.py "歌名" 一键下载音频+歌词+封面。

第二步：修改配置#

将 mode 改为 "local"，并配置播放列表：

1
export const musicPlayerConfig: MusicPlayerConfig = {
2
    mode: "local",
3

4
    local: {
5
        playlist: [
6
            {
7
                name: "知我",
8
                artist: "国风堂",
9
                url: "/assets/music/知我.mp3",
10
                cover: "/assets/music/cover/知我.webp",
11
                lrc: "/assets/music/lrc/知我.lrc",
12
            },
13
            {
14
                name: "女孩",
15
                artist: "韦礼安",
16
                url: "/assets/music/女孩.mp3",
17
                cover: "/assets/music/cover/女孩.webp",
18
                lrc: "",
19
            },
20
        ],
21
    },
22
};

字段说明#

添加更多歌曲#

方式一：使用下载脚本（推荐）

1
python scripts/download_music.py "歌名"
2
# 脚本会输出配置信息，复制粘贴到 playlist 数组即可

方式二：手动添加

只需在 playlist 数组中追加新条目：

1
playlist: [
2
    // ... 已有歌曲
3
    {
4
        name: "新歌曲名",
5
        artist: "新歌手名",
6
        url: "/assets/music/新歌曲.mp3",
7
        cover: "/assets/music/cover/新封面.jpg",
8
        lrc: "",
9
    },
10
],

更改封面#

封面图片要求：

• 推荐尺寸：300x300 像素
• 推荐格式：JPG 或 WebP
• 放在 public/assets/music/cover/ 目录

快速获取封面： 使用 python scripts/download_music.py "歌名" 会自动下载封面。

在配置中引用：

1
{
2
    name: "歌曲名",
3
    artist: "歌手名",
4
    url: "/assets/music/歌曲.mp3",
5
    cover: "/assets/music/cover/新封面.jpg",  // 修改这里
6
}

LRC 歌词文件格式#

LRC 是标准的歌词时间轴格式：

1
[00:00.00]歌曲标题
2
[00:01.00]歌手名
3
[00:05.00]第一句歌词
4
[00:10.50]第二句歌词
5
[00:15.20]第三句歌词

格式：[分:秒.毫秒]歌词内容

获取 LRC 歌词的方式：

• 网易云音乐网页版 → 开发者工具 → 搜索 lrc 获取歌词接口
• 使用 Python 脚本批量下载（如 fetch-lrc.py）
• 手动编写

工具一：Python 下载脚本（推荐）#

scripts/download_music.py — 一条命令完成搜索、下载音频、歌词、封面。

环境要求： Python 3.6+

基本用法：

1
# 搜索并下载（交互式选择歌曲）
2
python scripts/download_music.py "知我"
3

4
# 指定输出目录
5
python scripts/download_music.py "海阔天空" --dir=./my-music

执行流程：

1
搜索 → 显示结果列表 → 选择歌曲 → 下载 MP3 + LRC 歌词 + 封面 JPG

输出示例：

1
  Searching: 知我
2

3
  Results:
4
  [1] 知我 - 国风堂, 哦漏
5
  [2] 知我（抒情版） - 尘ah.
6
  [3] 肘我（知我加速版） - 神白sang
7

8
  Select [1]: 1
9

10
  Selected: 知我 - 国风堂, 哦漏
11
  Downloading audio...
12
  Music: 知我.mp3
13
  Lyrics: 知我.lrc
14
  Downloading cover...
15
  Cover: cover/知我.jpg
16

17
  ─────────────────────────────────────────
18
  Done! All files saved to public/assets/music/
19

20
  Add to musicConfig.ts local.playlist:
21
  { name: "知我", artist: "国风堂, 哦漏",
22
    url: "/assets/music/知我.mp3",
23
    cover: "/assets/music/cover/知我.jpg", lrc: "" }
24
  ─────────────────────────────────────────

工作原理：

注意事项：

• 封面通过抓取网易云歌曲网页的 og:image 标签获取，无需 API 认证
• 部分 VIP 步曲无法下载音频，脚本会提示手动下载
• 输出文件自动放在 public/assets/music/ 目录
• 文件名自动清理特殊字符（/\?%*:|" 等替换为 -）
• 已存在的文件不会被覆盖

工具二：M4A/MP3 元数据提取#

pnpm cli lrc — 从本地 M4A 或 MP3 文件中提取内嵌的封面和歌词。

用法：

1
# 提取单个文件
2
pnpm cli lrc 歌曲.m4a
3

4
# 提取整个目录
5
pnpm cli lrc /path/to/music/

支持格式：

输出示例：

1
  Cover: 歌曲.jpg
2
  Lyrics: 歌曲.lrc

适用场景：

• 从其他渠道获取了 M4A/MP3 文件，需要提取封面和歌词
• 音乐文件内嵌了元数据，想自动提取而不是手动下载

推荐工作流#

场景 A：从零开始添加新歌

1
# 1. 搜索 + 下载（音频+歌词+封面全自动）
2
python scripts/download_music.py "海阔天空"
3

4
# 2. 把脚本输出的配置信息添加到 musicConfig.ts
5
# 编辑 src/config/musicConfig.ts，加入 playlist 条目

场景 B：已有 M4A/MP3 文件

1
# 1. 把文件放到 public/assets/music/ 目录
2
# 2. 从文件中提取封面和歌词
3
pnpm cli lrc public/assets/music/歌曲.m4a
4

5
# 3. 手动添加配置到 musicConfig.ts

场景 C：批量导入

1
# 批量下载多首歌
2
python scripts/download_music.py "歌名1"
3
python scripts/download_music.py "歌名2"
4
python scripts/download_music.py "歌名3"
5

6
# 批量提取元数据
7
pnpm cli lrc public/assets/music/

MusicPage（独立音乐页面）#

位于 src/components/pages/MusicPage.astro，是 /music/ 页面的核心组件。

布局结构：

1
┌──────────────────────┬──────────────┐
2
│                      │ 播放列表      │
3
│   黑胶唱片封面        │ ┌──┬──┬──┐  │
4
│   （旋转动画）        │ │歌│歌│歌│  │
5
│                      │ ├──┼──┼──┤  │
6
│      歌名            │ │歌│歌│歌│  │
7
│      歌手            │ └──┴──┴──┘  │
8
│  ━━━━━━━━━━━━━━━━    │              │
9
│  0:00        3:45   │ 我的音乐收藏  │
10
│                      │ ┌──┬──┬──┐  │
11
│  ⟲  ⏮  ▶  ⏭  🔊   │ │♡ │♡ │♡ │  │
12
└──────────────────────┴──┴──┴──┘──┘
13
┌──────────────────────────────────────┐
14
│ 🎵 歌词          歌名 - 歌手        │
15
│  ┃                                    │
16
│  ┃  演唱：A-Lin黄丽玲                │
17
│  ┃  作词：邬裕康                      │
18
│  ┃  ...（自动滚动高亮当前行）          │
19
└──────────────────────────────────────┘

右侧包含两个独立区块：

• 播放列表：3 列网格，显示所有歌曲，点击播放
• 我的音乐收藏：3 列网格，显示已收藏歌曲（localStorage 存储）

下方歌词面板为独立卡片，蓝色左边框装饰，播放时自动滚动到当前歌词行。

MusicPlayer（侧边栏播放器）#

位于 src/components/features/MusicPlayer.astro，用于侧边栏和导航栏浮动面板。

工作原理#

歌词系统由 MusicManager 驱动：

1. 加载歌曲时，MusicManager 解析 LRC 文件或内嵌歌词字符串
2. 播放过程中，通过 fm:time 事件同步当前时间
3. 计算当前应高亮的歌词行，通过 fm:lrc-index 事件广播
4. MusicPage 监听事件，高亮对应行并自动滚动居中

LRC 歌词格式#

1
[00:00.00]歌曲标题
2
[00:01.00]歌手名
3
[00:05.00]第一句歌词
4
[00:10.50]第二句歌词

格式：[分:秒.毫秒]歌词内容

歌词来源#

方式一：LRC 文件（推荐）

将 .lrc 文件放在 public/assets/music/lrc/ 目录，在配置中引用：

1
{
2
    name: "歌曲名",
3
    artist: "歌手名",
4
    url: "/assets/music/歌曲.mp3",
5
    lrc: "/assets/music/lrc/歌曲.lrc",  // LRC 文件路径
6
}

方式二：内嵌歌词字符串

直接在配置中写入 LRC 格式字符串：

1
{
2
    name: "歌曲名",
3
    artist: "歌手名",
4
    url: "/assets/music/歌曲.mp3",
5
    lrc: "[00:05.00]第一句歌词\n[00:10.50]第二句歌词",
6
}

方式三：云端 API 自动获取

使用 Meting API 时，API 返回的数据中已包含 lrc 字段（LRC 格式字符串），无需额外配置。

获取 LRC 歌词#

• 自动化脚本（推荐）：使用内置 Python 脚本一键下载（详见下方「自动化工具」章节）
• 网易云音乐：网页版 → F12 开发者工具 → Network → 搜索 lyric → 找到歌词接口返回的内容
• 手动编写：用文本编辑器按 LRC 格式编写

歌词面板样式#

歌词面板位于播放器下方，带有蓝色左边框：

1
<div class="lyrics-panel border-l-4 border-l-(--primary)">
2
    <div class="lyrics-header">歌词</div>
3
    <div class="lyrics-container h-64 overflow-y-auto">
4
        <!-- 歌词行 -->
5
    </div>
6
</div>

修改歌词面板高度：

1
.lyrics-container {
2
    height: 16rem;  /* 默认 h-64，可改为 h-48 或 h-80 */
3
}

歌词自动滚动行为#

播放时歌词会自动滚动到当前行并居中高亮。滚动行为支持智能检测：

• 自动滚动：播放过程中，当前歌词行自动居中显示
• 手动滚动暂停：用户滚动歌词（鼠标滚轮或触摸滑动）时，累计滚动距离超过 50px 后暂停自动滚动
• 自动恢复：停止手动滚动 2 秒后，自动跳回当前歌词行并恢复自动滚动
• 点击跳转：点击任意歌词行可跳转到对应时间点播放

1
// 滚动检测核心逻辑
2
var scrollDeltaAccum = 0;
3
ui.lyricsContainer.addEventListener('wheel', function(e) {
4
    scrollDeltaAccum += Math.abs(e.deltaY);
5
    if (scrollDeltaAccum > 50) {
6
        isUserScrolling = true;  // 暂停自动滚动
7
        resetScrollTimeout();    // 2秒后恢复
8
    }
9
    // 300ms 内无新滚动则重置累积值
10
    clearTimeout(resetTimer);
11
    resetTimer = setTimeout(function() { scrollDeltaAccum = 0; }, 300);
12
});

工作原理#

收藏功能使用 localStorage 存储，无需后端：

1. 每首歌卡片右上角有 ♡ 收藏按钮
2. 点击后将歌曲信息 { name, artist, pic } 存入 localStorage
3. 右侧”我的音乐收藏”网格实时显示已收藏歌曲
4. 点击收藏卡片可播放对应歌曲
5. 悬停收藏卡片显示 ✕ 按钮，可取消收藏

存储结构#

1
// localStorage key: "music-favorites"
2
// value: JSON 数组
3
[
4
    { name: "知我", artist: "国风堂", pic: "https://..." },
5
    { name: "女孩", artist: "韦礼安", pic: "https://..." },
6
]

自定义收藏键名#

如需修改 localStorage 的 key，在 MusicPage.astro 的 <script> 中修改：

1
var FAVORITES_KEY = 'music-favorites';  // 改为你想要的 key

清空收藏#

在浏览器控制台执行：

1
localStorage.removeItem('music-favorites');

第一步：创建 MusicPage 组件#

在 src/components/pages/ 下创建 MusicPage.astro，包含：

1. 左侧播放器区域

   • 黑胶唱片封面（vinyl-ring 渐变圆环 + 内圈封面图）
   • 轨道信息（歌名、歌手）
   • 进度条（可点击跳转）
   • 控制按钮（循环、上一首、播放/暂停、下一首、音量）

2. 右侧收藏网格

   • 3 列网格布局
   • 每张卡片：封面图 + 歌名 + 歌手 + 收藏按钮

3. 底部歌词面板

   • 蓝色左边框装饰
   • 歌词头部信息栏
   • 可滚动歌词容器，自动高亮当前行

第二步：接入 MusicManager 事件系统#

MusicPage 通过监听 fm:* 自定义事件与 MusicManager 通信：

1
// 监听事件
2
window.addEventListener('fm:init', function(e) { /* 播放列表加载完成 */ });
3
window.addEventListener('fm:track', function(e) { /* 切换歌曲 */ });
4
window.addEventListener('fm:play-state', function(e) { /* 播放/暂停 */ });
5
window.addEventListener('fm:time', function(e) { /* 进度更新 */ });
6
window.addEventListener('fm:lyrics', function(e) { /* 歌词加载 */ });
7
window.addEventListener('fm:lrc-index', function(e) { /* 歌词行高亮 */ });
8
window.addEventListener('fm:volume', function(e) { /* 音量变化 */ });
9
window.addEventListener('fm:mode', function(e) { /* 播放模式变化 */ });
10

11
// 调用 API 控制播放
12
window.__fireflyMusic.togglePlay();      // 播放/暂停
13
window.__fireflyMusic.playNext();        // 下一首
14
window.__fireflyMusic.playPrev();        // 上一首
15
window.__fireflyMusic.seek(percent);     // 跳转进度 (0-1)
16
window.__fireflyMusic.setVolume(val);    // 设置音量 (0-1)
17
window.__fireflyMusic.cyclePlayMode();   // 切换播放模式
18
window.__fireflyMusic.playTrackByIndex(i); // 播放指定歌曲

第三步：更新 music.astro 页面#

将 src/pages/music.astro 改为使用 MusicPage 组件：

1
---
2
import MainGridLayout from "@/layouts/MainGridLayout.astro";
3
import MusicPage from "@/components/pages/MusicPage.astro";
4
---
5

6
<MainGridLayout title="音乐" description="我喜欢的音乐">
7
    <div class="flex w-full rounded-(--radius-large) overflow-hidden relative min-h-32">
8
        <div class="card-base z-10 px-6 md:px-9 py-6 relative w-full">
9
            <MusicPage />
10
        </div>
11
    </div>
12
</MainGridLayout>

第四步：配置音乐源#

编辑 src/config/musicConfig.ts，选择 meting 或 local 模式（详见上方配置章节）。

第五步：验证#

1
pnpm dev

访问 /music/ 检查：

• 黑胶唱片封面旋转动画
• 播放控制功能正常
• 歌词自动滚动高亮
• 收藏/取消收藏功能
• 收藏数据刷新后保留

修改播放器颜色#

播放器使用 CSS 变量 --primary 作为主题色，在 src/styles/main.css 中修改：

1
:root {
2
    --primary: oklch(0.65 0.15 250);  /* 蓝色 */
3
}

修改唱片旋转速度#

在 MusicPage.astro 的 <style> 中修改：

1
@keyframes vinyl-spin {
2
    from { transform: rotate(0deg); }
3
    to { transform: rotate(360deg); }
4
}
5

6
.vinyl-ring {
7
    animation: vinyl-spin 20s linear infinite;  /* 改这里的 20s */
8
}

修改歌曲网格列数#

在 MusicPage.astro 中修改 grid 类：

1
<div class="song-grid grid grid-cols-3 gap-3">

改为 grid-cols-2（2 列）或 grid-cols-4（4 列）。

Q: 音频无法播放？#

检查：

1. 音频文件是否在 public/assets/music/ 目录下
2. 配置中的路径是否正确（相对于 public/）
3. 浏览器控制台是否有 CORS 错误（云端音频需要 crossOrigin = 'anonymous'）

Q: 封面不显示？#

检查：

1. 图片文件是否存在
2. 路径是否正确
3. 图片格式是否被浏览器支持
4. 使用 python scripts/download_music.py 下载的封面会自动放在 cover/ 目录

Q: Python 脚本下载失败？#

常见原因及解决方案：

Q: pnpm cli lrc 提取不到封面？#

1. 确认文件是 .m4a 或 .mp3 格式
2. 确认文件内嵌了封面数据（部分下载的 MP3 没有内嵌封面）
3. 使用 python scripts/download_music.py 下载的歌曲会自动获取封面

Q: Meting API 不可用？#

1. 检查网络连接
2. 尝试切换其他备用 API
3. 如果所有 API 都不可用，系统会自动回退到本地播放列表
4. 也可以直接将 mode 改为 "local" 使用本地文件

Q: 如何禁用音乐播放器？#

在 musicConfig.ts 中：

1
export const musicPlayerConfig: MusicPlayerConfig = {
2
    showInNavbar: false,  // 禁用导航栏入口
3
};

侧边栏播放器在 src/config/sidebarConfig.ts 中将 music 组件的 enable 设为 false。