聚合音源架构深扒：lx-ikun-music-sources中Promise.allSettled多平台降级机制的设计原理

聚合音源架构深扒：lx-ikun-music-sources中Promise.allSettled多平台降级机制的设计原理

【免费下载链接】lx-ikun-music-sourcesLX_music & IKUN_music 音源收集项目地址: https://gitcode.com/gh_mirrors/lx/lx-ikun-music-sources

lx-ikun-music-sources 是面向 LX Music 与 IKUN Music 的音源收集仓库，其中最值得研究的是「全豆要-聚合音源」：它把星海、溯音、念心、长青等多个音源封装成一条链路，利用Promise.allSettled实现多平台并发请求与自动降级回退。本文带你从架构分层、并发策略到缓存降级，逐层拆解这套聚合音源设计原理，帮助新手理解「音源挂了还能听」背后的工程思路。

为什么需要「聚合音源」架构

用过的音源都懂：单一音源接口经常面临三种情况——接口下线、密钥失效、服务器抽风。

上表是仓库整理者对多个音源的实测结果：即便是优质音源，跨平台成功率也往往只有 70%~100% 不等，单个平台（如咪咕、酷狗）不支持的情况非常普遍。

聚合音源的核心思路：不把希望寄托在一条链路上，而是把 N 个音源注册成一个处理器池，按歌曲所属平台动态组装出「音源链」，请求时自动降级回退——一个源挂了，玩家完全无感。

三层架构：聚合音源是怎么搭起来的

以 全豆要-聚合音源 v9.3 93特供版.js 为样本，整个机制可以拆成三层：

1️⃣ 音源处理器注册表：统一接口

每个音源（星海、Huibq、溯音、聆川、长青、念心……）都被包装成同一个签名{ name, fn }，注册进SOURCE_HANDLERS表。这样上层逻辑不关心「这是谁的接口、参数怎么拼」，只调用统一的fn(platform, songId, quality, songInfo)。

对应源码位置：SOURCE_HANDLERS注册表与buildSourceChain函数（约 L720–L747）

这是典型的「策略模式」：把每种音源变成一个可替换的策略对象，新增音源只需往表里加一行。

2️⃣ 音源链构建器：按平台动态组装

buildSourceChain(platform, isHires, quality)根据歌曲平台（tx/QQ、wy/网易云、kw/酷我、kg/酷狗、mg/咪咕）从注册表里挑出可用处理器，按优先级排成一条链：

星海主 → Huibq → 溯音(对应平台) → 聆川 → 长青SVIP → 念心SVIP

链的排列顺序就是「先试谁、后试谁」，靠前的接口速度快、覆盖面广，靠后的接口是兜底。

3️⃣ 降级执行器：getUrlWithFallback

真正干活的是getUrlWithFallback（约 L750–L786），它采用两段式降级策略：

• 前 3 个源：并发请求（快，省时间）
• 剩余源：逐个顺序请求（稳，省流量）

核心机制：Promise.allSettled 并发降级详解

前 3 个源的并发阶段是全文最关键的一小段（约 L765–L774）：

const firstBatch = chain.slice(0, 3); // 前3个源 const results = await Promise.allSettled( firstBatch.map(handler => handler.fn(platform, songId, quality, songInfo).then(url => validateUrl(url, handler.name)) ) ); for (const result of results) { if (result.status === "fulfilled") return result.value; // 第一个成功立即返回 errors.push(result.reason?.message); // 失败原因全部收集 } // 前3个都挂了 → 顺序尝试剩余源 for (const handler of chain.slice(3)) { /* try/catch 逐个试 */ } throw new Error(`所有源均失败: ${errors.join("; ")}`);

Promise.allSettled的语义是：等待所有并发请求都有结果（成功或失败），谁先成功不影响其他请求的执行。这带来三个好处：

为什么不用 Promise.all / Promise.any？

这正是 v9.3 版本的重点改动，更新日志中明确写着（见 全豆要 更新日志 v9.3.txt）：

改进 fallback 并发机制：将 Promise.any 替换为 Promise.allSettled，兼容性更好，且能收集所有错误信息

三兄弟对比一下就很清晰：

• Promise.all：任何一个源失败，整体立即 reject——第一个源抽风，后面两个明明可能成功的源就直接被判死刑，没有降级能力。
• Promise.any：只要有一个源成功就 resolve——看似够用，但它会丢弃其余请求的错误信息（失败原因无从知晓），且在较旧的 JS 运行时中兼容性差。
• Promise.allSettled：等齐所有结果后逐个处理，既能短路返回第一个成功 URL，又能把每个失败源的错误全部收进错误清单，兼容性和可调试性双赢。

这也是「多平台降级机制」里「降级」二字的精髓：失败不是终点，而是触发下一条链路的路标。

稳定性另一半：缓存与音质降级

并发降级解决「能不能拿到 URL」，另外两个机制解决「拿得省不省、对不对」：

1. URL 缓存：CACHE_TTL_MS = 21600000（6 小时）+ 最多 500 条的 LRU 淘汰（约 L407–L432）。同一首歌 6 小时内重复播放直接命中缓存，不再打扰音源接口，也降低接口被限流的概率。
2. 音质自动降级：selectQuality配合QUALITY_PRIORITY优先级数组，当某音源不支持你请求的 flac 时，自动向下匹配该源支持的最高音质（flac → 320k → 128k），保证「有得听」优先于「听最高音质」。

调这些接口时最怕的就是满屏报错，排查半天最后发现是源本身挂了——


有了全量错误收集，你只需要看最后那条「所有源均失败: ...」的报错，就能精准定位是哪一条链路的问题。

新手实用建议：如何在仓库里选聚合音源

• 优先从「优质」分类入手：0 优质/ 目录下的音源经过多平台 FLAC 测试，聚合类音源（全豆要、聚合API等）都放在这里；
• 仓库按日期版本归档（如 files/v260611/、V260328/），新号建议直接取最新批次，老接口大概率已失效；
• 播放端配置时，把聚合音源排在音源列表最前，单平台音源（酷我/网易专用）放后面兜底，配合 LX Music 的音源优先级机制，体验最佳；
• 需要自行配置密钥的音源（如 Huibq、聆川），记得先看文件头部的常量区，把HUIBQ_API、HUIBQ_REQUEST_KEY等占位符替换成有效值。

小结

这套架构用三个经典手法解决了音源生态「接口不稳定」的老大难问题：

1. 策略模式注册音源处理器，新源一行接入；
2. 两段式降级（前 3 并发 + 剩余顺序）平衡速度与流量；
3. Promise.allSettled全量收集错误 + 短路返回，兼顾兼容性与可调试性。

再叠加 6 小时 URL 缓存与音质自动降级，聚合音源就成了「多平台 FLAC 播放」最稳的解法。理解了这套设计，你甚至可以在自己的项目里复刻同样的「多后端自动回退」机制——毕竟，Promise.allSettled不只是音源圈的救星，更是所有高可用请求链路的标配。

【免费下载链接】lx-ikun-music-sourcesLX_music & IKUN_music 音源收集项目地址: https://gitcode.com/gh_mirrors/lx/lx-ikun-music-sources