无头音乐下载器Ro实战：151首歌单的清洗、换源下载与歌词封面自动化

前言

博客音乐库原本只有 91 首周杰伦（见《液态玻璃音乐播放器》一篇），一直想扩容，但手动加歌的流程实在太长：找下载源、抓歌词、配封面、改 manifest，每首歌五分钟起步。直到发现了开源项目 Ro——一个无头（headless）音乐下载服务，支持多平台搜索、自动嵌入歌词封面、歌单批量下载，我意识到曲库供给端可以被完全自动化。

于是有了这次实践：一份 QQ 音乐收藏歌单（160 首），经过清洗、匹配、下载、换源兜底、歌词抓取、封面提取、入库，最终曲库从 91 首涨到 241 首，全程没有手动配过一首歌的元数据。本文记录整条链路的设计与踩坑。

一、Ro 是什么：两套系统各管一半

Ro（Apache-2.0）基于 lx-music（洛雪音乐）音源生态，Fastify + TypeScript + SQLite 实现，带 Web 后台和 REST API。理解它的关键是知道它的职责被切成了两半：

Ro 把这些来路不明的音源脚本关进 node:vm + worker_threads 双层沙箱运行，只向脚本问一个问题："这首歌在指定音质下的直链是什么"，拿到 URL 后自己去流式下载并嵌入元数据。搜索接口的每个结果都带各音质的精确体积，下载前就能看到 128k/320k/flac 各是多大。

部署选了 README 的方式三（本机没有 Docker）：Node ≥ 20 直接跑，npm install 时 better-sqlite3/sharp 都命中了预编译包，没有触发本地编译。两处配置值得注意：server.host 改成 127.0.0.1（这类服务不该暴露到局域网之外），登录密码必须非空。

二、歌单清洗：归一化匹配，宁漏勿删

歌单是从 QQ 音乐收藏导出的 JSON：歌单显示 536 首，工具实际识别出 160 首，每条只有"歌名 + 歌手"。清洗的目标是剔除博客曲库里已有的歌，核心是相似但不误伤：

// 三层归一化,再按「歌名相等 + 歌手有交集」判重
const norm = s => (s || '').normalize('NFKC').toLowerCase().replace(/\s+/g, '');
// 尾部括号后缀逐层剥离:「突然的自我 (Live)」→「突然的自我」
// 歌手按 / & 、 feat. 等拆成 token,token 互含也算交集

几个容易误杀的场景全部靠"歌手交集"这一条守住：歌单里《哭不出来》有张惠妹和周杰伦两个版本、《突然的自我》有伍佰和黄小琥两版——同名不同歌手，一律保留。最终剔除了 7 首曲库已有曲目，外加 2 首以"7.10万兽之王薛之谦"命名的无效录音（歌手是"未知歌手"，任何平台都搜不到），160 → 151 首。原文件永远备份一份 .bak 再动手。

三、批量下载：第一轮近半阵亡，换源全歼

下载是三段式：逐首搜索匹配 → 批量提交 → 轮询任务。脚本按歌名+歌手在 QQ 音乐平台搜索，用与清洗相同的匹配规则选中结果，整单提交给 /api/v1/download/batch（320k 音质），然后轮询任务状态。

第一轮结果：74 成功，77 失败，失败清一色 HTTP 404。这是音源直链失效——第三方解析 API 返回的 URL 有时效性，批量请求时过期就 404。对 Ro 的任务重试接口抱了希望，结果重试后依然全灭：这个音源对这批歌的解析是稳定性挂掉，不是偶发。

真正的解法是换平台：对 77 首失败的歌改用酷我（kw）平台重新搜索匹配再提交——77 首全部救回。Ro 内置的音质降级链和跨平台换源兜底在这里也功不可没，但"整批换平台重下"这种粒度的自救还是得自己写。

这一段踩了三个工程坑，都值得记下：

1. Git Bash 里 curl 直接传中文 JSON 会报 Content-Length 不匹配——命令行编码把多字节字符搞乱了。解法：请求体写成 UTF-8 文件，curl --data-binary @body.json；
2. Ro 的 retry 接口对"带 JSON 头但空 body"的请求直接 400（Fastify 的 body 解析器拒绝），要传 {}。我第一版重试脚本 77 发 77 被拒，日志上一行"重试成功"都没有——认真读错误信息比什么都重要；
3. /tasks 列表只返回最近 200 条，批量任务一多旧任务会被滚出列表，轮询统计严重失真。最后放弃接口对账，改用磁盘文件与歌单逐条严格匹配做真实差集——"以磁盘为准"这四个字在批量下载场景里永远成立。

顺带一提音质选型：128k 约 4MB/首、320k 约 10MB/首、FLAC 20-90MB/首。在线播放场景 320k 是体验与流量的平衡点，FLAC 留给本地收藏。

四、歌词：QQ 接口为主力，放宽策略补漏

博客播放器的歌词同步靠外挂 .lrc 文件，所以每首歌还要抓一份带时间轴的 LRC。主力方案延续了之前给 91 首歌配词的思路：QQ 音乐公开接口，搜索拿 songmid → 歌词接口返回 base64 编码的 LRC → 解码落盘（记得带 Referer: y.qq.com）。酷狗的歌词接口（krcs.kugou.com，按 hash 换 accesskey 下载）写好了做兜底，但全程没轮到出场。

第一轮 150 首拿下 148 首，剩 2 首都是演唱会 Live 版，严格匹配搜不到。放宽策略补齐：全名搜索、去掉歌手约束再搜，结果《爱情 (2007世界巡回演唱会香港站)》直接找到了完全同版的现场歌词，《0932》用录音室版歌词顶上。这也带来一个已知瑕疵：Live 录音配标准歌词，逐句时间戳会有漂移——QQ 音乐自己的现场版歌词也是这个状态，不影响使用。

顺带验证了用户提的 openflac.com：挂着 Cloudflare 的 JS 盾（"Just a moment..."挑战页），带浏览器 UA 的请求也过不去，程序化爬取需要真实浏览器执行脚本。好在没它什么事。

五、封面：嵌入标签 → 提取为外挂文件

Ro 下载时默认把歌词和封面嵌入音频标签（MP3 的 APIC/USLT 帧，FLAC 的 METADATA_BLOCK_PICTURE）。但博客的播放器是通过 manifest 的 cover 字段用 <img> 加载外挂图片的，浏览器没法直接读音频标签——所以入库时要把封面提取出来存成文件：

const meta = await mm.parseFile(mp3Path);
const pic = meta.common.picture && meta.common.picture[0];
fs.writeFileSync(`covers/t${n}.jpg`, pic.data);   // 500px JPEG,约 60KB/张

这其实是一个"嵌入 vs 外挂"的体系选择：嵌入的好处是文件自带元数据、拷到手机本地播放器直接显示；外挂的好处是 Web 体系里可控可引用。两者不冲突——文件里嵌着（保底），入库时抽出来（供 Web 用）。

六、入库：延续命名，守卫放行有度

博客曲库的文件命名有两个历史时期：t01..t83 和 track1..track8，新歌统一延续 t 系列：t84..t233。入库脚本对每首歌做四件事：复制音频与同名 .lrc 到对应目录、从标签提取封面、按"歌名-歌手"约定追加 manifest 记录。脚本内置重复守卫（与清洗相同的匹配规则），任何与现有曲库或本批次撞车的歌都会被拦下人工确认。

守卫拦下了一个真实案例：《你怎么舍得我难过》在歌单里有两个版本，下载后一比对——周杰伦/黄品源合唱版只有 99 秒、128kbps（现场片段），黄品源版是 295 秒完整歌曲。两个不同录音、各有收藏价值，最终都入了库。如果只要一个，守卫默认留第一个，人工复核再定夺。

最终曲库 91 → 241 首，新增资产约 1.1GB（150 首 320k 音频 + 歌词 + 150 张封面），manifest 一份文件全部承载，前端零改动。

七、前端配套：队列计数与封面懒加载

曲库翻倍后，播放列表一次性渲染 241 个条目暴露了一个问题：每张队列缩略图都是完整加载（约 60KB/张，全量 10MB+）。解决方案是封面懒加载：

// 图片先不带 src,贴上 data-src;IntersectionObserver 临近视口 300px 才真正请求
lazyIO = new IntersectionObserver(entries => {
  entries.forEach(en => {
    if (!en.isIntersecting) return;
    en.target.src = en.target.getAttribute('data-src');
    lazyIO.unobserve(en.target);
  });
}, { rootMargin: '300px 0px' });

首屏只请求十几张图，滚动到哪加载到哪；不支持 IntersectionObserver 的环境直接降级为全量加载。歌词和音频本来就已经是按需的（切歌才 fetch 歌词，audio.preload = 'metadata' 只拉元数据），至此播放列表的全部大资源都是懒加载。顺手给 "Up Next" 标题加上了总数（Up Next · 共 N 首），曲库规模一目了然。

manifest 本身 241 条也就几十 KB，服务端渲染时内联进页面（window.MUSIC_LIST）依然是正确的选择。

八、数字盘点

结语

整条链路跑下来，最大的体会有三条。其一，"以磁盘为准"：批量任务的中间状态（接口返回的任务列表、状态统计）都可能失真，唯一可信的是最终落盘的文件，对账永远对着终点做。其二，换源即冗余：第三方音源的可用性完全取决于社区解析 API 的存亡，这次 77 首 404 与 77 首全救回发生在同一个小时内——多一个平台候选就多一层保险，这个思路对任何依赖外部服务的系统都成立。其三，嵌入与外挂各司其职：音频标签里的元数据面向"文件自身便携性"，外挂文件面向"Web 体系的引用"，入库脚本就是把前者转译成后者的桥梁。

遗留事项也如实记录：Live 版歌词存在时间戳漂移；有一首 99 秒的现场片段混在曲库里，待人工取舍；Ro 自带的健康冒烟测试每天早上六点会自动跑一次真实下载链路，音源大面积失效时能第一时间知道。至于版权——这套东西的定位是个人自用的曲库维护工具，边界自己心里有数就好。

如果这篇文章帮你少踩了坑，欢迎在评论区聊聊你的音乐库自动化方案。