更新：2026-09-08 · 全平台结构审计 94 项 0 异常（先 node server.js，再运行 node test-structure.js 等回归脚本）。
路由 支持的 source /api/search tx,wy,kg,kw,qianqian,5sing,bodian,mg,soda,streetvoice,apple,xm(单集),lizhi(声音),qingting(节目) /api/album/search tx,wy,kg,kw,qianqian,mg,soda,apple,xm,lrts(书/专辑),qingting(频道) /api/singer/search tx,wy,kg,kw,qianqian,5sing(精确),mg,soda,apple /api/playlist/search tx,wy,kg,kw,5sing,mg,xm /api/playlist/recommend tx,wy,kg,kw,qianqian,5sing(首页推荐15),xm /api/playlist/tags tx,wy,kg,kw,qianqian,xm,lrts(书籍分类),qingting(频道分类) /api/playlist/list tx,wy,kg,kw,qianqian,xm,lrts(分类下书),qingting(分类下频道) /api/playlist/detail tx,wy,kg,kw,qianqian,5sing,bodian,mg,xm,lrts(kind=book/album),lizhi(kind=user),qingting(kind=channel) /api/leaderboard/list 真实: tx,wy,kg,kw,qianqian(7榜),5sing(3榜),mg(9榜),xm,lrts(书城6榜×3周期) / 200空stub: soda,streetvoice,apple,bodian,lizhi,qingting /api/leaderboard/detail 同上（真实源返回行；stub 返回 200 空结构） /api/lyric tx,wy,kg,kw,qianqian(词文件),5sing(LRC),bodian(复用酷我),mg(LRC),streetvoice(纯文本) /api/hotsearch tx,wy,kg,kw,mg(运营词),xm/lrts/lizhi/qingting(平台内容词兜底) / 其余平台为空占位 /api/url tx..kw(音源聚合) qianqian,5sing,bodian,soda,streetvoice,apple,xm,lrts,lizhi,qingting(需配置) / mg 返回 null(受限) 评论/MV/专辑详情/歌手详情/图片：仅 tx,wy,kg,kw（新平台上游无公开源）
说明：喜马拉雅为音频节目，无 128k/320k/flac 档位概念；单集 ID 即搜索结果中的 id。 免费集可正常取播放地址，付费/未授权集 /api/url 返回 null。官方高音质（官方v1）需登录态， 当前按 musicdl 顺序自动降级：电信镜像 → 官方v1 → 官方v2 → cgg。 排行榜（2026-09 恢复为真实数据）：榜单列表=官网 revision/rank v4 rankTabs（匿名，133 榜动态）； 榜单详情=element 接口，一次返回全榜 100 个专辑行（含主播/封面/播放量/集数/付费态），需 xm-sign 请求头—— 签名有效期分钟级且无法本地生成，本服务会自动启动本机无头 Edge/Chrome 抓取并缓存 5 分钟（约 8s 冷启动/次）； 无浏览器环境时可手动抓取并设环境变量 XM_SIGN：node scripts/xm-fetch-sign.mjs（签名过期时返回 400 提示）。
说明：懒人听书分「书」（有声书/广播剧，kind=book）与「专辑/节目」（kind=album）两类， 均按现有专辑语义返回：集数行含 id/name/duration/durationText/section 等，播放地址返回 m4a 直链。 书单集播放需 containerId(书ID)+section(第几集,从1起)+songId(章节ID)；专辑单集需 containerId(专辑ID)+songId(audioId)。 免费内容可直接播放；付费整本/整辑（VIP）目录或地址返回 null，行为与喜马拉雅付费集一致。 分类标签/分类列表（分类页无 JSON 接口）由官网 www.lrts.me 静态页解析：分类下书列表行=有声书专辑（kind=book）， 行含 id/name/author(主播)/img/desc，与书搜索行结构一致，可直接进书目录详情；页面上限 20/页。 站点边缘缓存偶发返回空行版页面，接口内部自动带时间戳重试（test-tags.js 回归）。
说明：荔枝为播客/声音平台，单集=声音(voice)。搜索返回歌曲行（id/songmid=voiceId、singer=主播名）； 单集直接由 voiceId 取播（详情接口 trackUrl，缺失时按封面日期拼 CDN）；容器=主播主页（kind=user）。 接口页大小站点固定，total 为 0（未知），hasMore 布尔字段指示是否还有下一页。 回归测试：cd api/music && node test-lizhi.js。
说明：musicdl qianqian 语义，MD5 自签（secret 静态）免登录；搜索行 name/singer/img 等字段与其它平台一致； 个别无版权歌曲 tracklink 返回 null。回归测试：cd api/music && node test-extra.js。
说明：纯明文免登录；URL 按 无损(sq)→高品(hq)→低品(lq) 含 *_backup 兜底； 搜索行额外带 songtype 字段（yc/fc/bz），播放时随 URL 请求回传。
说明：免登录；VIP 歌曲播放自动降级 29s 试听。
说明：浏览能力全量；播放因官方免签收紧返回结构化 null（不报错）。
说明：歌单/榜单需登录态未提供；播放走 share 双入口（music.douyin 与 douyin.com/qishui/song）加固解析。
说明：全链路免登录免 cookie；固定 96kbps MP3-HLS。
说明：搜索/频道/集数匿名可用；播放需环境变量 QINGTING_ACCESS_TOKEN / QINGTING_ID（见下方统一账号配置）。 分类标签/分类列表（App m-bff 无公开分类 JSON，实测 400）由 www.qingting.fm 网页解析： 列表行=专辑型频道（kind=channel，与频道搜索行结构一致，可进频道集数详情）；直播/电台行无节目分页故不返回。 页面为华为云 WAF 防护，高频请求会出 Access Verification 校验页，接口自动退避重试（test-tags.js 回归）。
已接入：歌曲 10（tx/wy/kg/kw/qianqian/5sing/bodian/mg(浏览)/soda/streetvoice + apple 预览档）+ 听书 4（xm/lrts/lizhi/qingting(浏览+配置播放)）。
播放受限说明：咪咕（官方免签收紧，返回 null）、蜻蜓（需账号配置）、Apple 整曲（需配置 token，未配置自动 30s 预览）。
番茄畅听（fanqiechangting）：主域已死且无公开音频接口（App 私有签名网关），服务端不可接入，已做调研记录。
B站（bilibili）：按需移除，暂不接入。
海外平台（YouTube/Spotify/Apple Music 整曲/JOOX/TIDAL 等）：暂不接入，与现有国内服务器架构不匹配。
常态化更新：各平台模块位于 api/music/src/<平台>/；回归脚本 api/music/test-*.js（真实网络）；结构审计 node test-structure.js。
口径：接口路由、行为与输出结构对齐基准；✓=真实数据，stub=上游无公开源但返回 200 空结构（不伪造数据），—=上游无且语义不适用。
【音乐类 vs QQ(tx)】
接口 tx qianqian 5sing bodian mg soda streetvoice apple
单曲搜索 ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓(iTunes)
播放URL ✓ ✓ ✓ ✓(整曲/试听) —(受限null) ✓(126k) ✓(HLS) ✓(30s预览)
歌词 ✓ ✓(词文件) ✓(LRC) ✓(复用酷我) ✓(LRC) —(无公开) ✓(纯文本) —(无公开)
歌手搜索 ✓ ✓ ✓(精确) — ✓ ✓ — ✓(iTunes)
专辑搜索 ✓ ✓ — — ✓ ✓ — ✓(iTunes)
歌单搜索/详情/分类/推荐 ✓(全) qianqian(推荐/详情/分类/列表,无关键词搜索) 5sing(搜索/详情/首页推荐) bodian(详情) mg(搜索/详情) — — —
榜单/详情 ✓ ✓(7榜) ✓(原创榜) stub ✓(9榜) stub stub stub
热搜 ✓ stub stub stub ✓(运营词) stub stub stub
歌单标签/列表 ✓ ✓(分类) — — —(分类树真,列表无公开) — — —
评论/MV/歌手详情/专辑详情/图片/导入 ✓(tx真实) 其余：上游无公开接口 → 不提供（客户端按平台降级），文档记录
注：咪咕标签维度实测分类树为真实数据，但「分类→歌单列表」上游仅返回模板占位/需签名（无公开 JSON），
标签与列表必须成对可用才提供，故 /api/playlist/tags?source=mg 返回 400 不支持的源。
【听书类 vs 喜马拉雅(xm)】 接口 xm lrts(懒人) lizhi(荔枝) qingting(蜻蜓) 单集搜索 ✓ —(容器语义) ✓(声音) ✓(节目) 专辑/书搜索 ✓ ✓(书/专辑) —(无合集) ✓(频道) 集数列表(详情) ✓ ✓(书目录/专辑) ✓(主播主页) ✓(频道) 单集播放URL ✓ ✓(m4a) ✓(直链) ○(需token配置) 分类标签/列表 ✓ ✓(17类网页) — ✓(27类网页) 榜单/榜单详情 ✓(133,自动签) ✓(6榜×3周期,前20) — — 热搜 ✓ ✓(词兜底) ✓(词兜底) ✓(词兜底) 付费解锁 ○(XM_COOKIE) — — ○(QINGTING_ACCESS_TOKEN) 说明：行内字段已统一（durationText/paid/source/kind 等）；无上游接口的维度返回 200 空占位不报错。 喜马拉雅榜单详情签名（xm-sign）有效期分钟级：服务有 Edge/Chrome 时自动无头抓取并缓存 5 分钟（约 8s 冷启动/次）； 无浏览器环境可设环境变量 XM_SIGN（node scripts/xm-fetch-sign.mjs 抓取），过期返回 400 提示。 懒人听书榜单深页对游客为空（站点仅 SSR 第 1 页 20 行），p≥2 返回空列表不伪造。
★=完整可用；○=可用但受限；—=该平台无此维度（上游无公开稳定接口）。所有新平台输出字段与四主流/喜马拉雅同构。
【歌曲类】 平台 单曲搜索 播放URL 歌词 歌单详情 榜单/热搜 评论 MV/歌手/专辑 QQ(tx) ★ ★ ★ ★ ★ ★ ★ 网易云(wy) ★ ★ ★ ★ ★ ★ ★ 酷狗(kg) ★ ★ ★ ★ ★ ★ ★ 酷我(kw) ★ ★ ★ ★ ★ ★ ★ 千千(qianqian)★ ★ ★(词文件) ★(推荐/分类/详情) ★(7榜单) — ★(歌手/专辑搜索) 5sing ★ ★(sq/hq/lq) ★(LRC) ★(搜索/详情) ★(原创榜JSON50/翻唱榜/伴奏榜HTML100) — ★(音乐人精确搜索) 咪咕(mg) ★ —(官方免签播放收紧,返回null) — ★(搜索/分类/详情) ★(9榜单/热搜) — ★(歌手/专辑搜索) 汽水(soda) ★ ★(整曲126k m4a,免登录) — — — — ★(专辑/歌手搜索) 街声(streetvoice) ★(官方JSON) ★(HLS m3u8 96k) ★(纯文本) — — — — Apple(apple) ★(iTunes) ★(30s预览;整曲需配置token) — — — — — 【听书/有声类】 平台 单集搜索 专辑/书搜索 集数列表(详情) 单集播放URL 分类/榜 其他 喜马拉雅(xm) ★ ★ ★ ★ ★(分类/榜/热搜) 评论(有) 歌词(无) 懒人听书(lrts) —(按容器) ★(书/专辑) ★(书目录/专辑集数) ★(m4a) — 说明:字段与xm同构,付费返回null 荔枝(lizhi) ★(声音) — ★(主播主页 kind=user) ★(直链) — — 蜻蜓(qingting) ★(节目搜索) ★(频道搜索) ★(频道集数) ○(需配置QINGTING_ACCESS_TOKEN/QINGTING_ID;未配置needConfig) Apple Music 暂缓(延后档: preview 免费 / 整曲需 media-user-token)
说明：当前档位=官方 30 秒预览（audio/x-m4p，免账号）。整曲解锁：设置环境变量 APPLE_MEDIA_USER_TOKEN （Apple Music 登录态 cookie 中的 media-user-token）后重启；未配置自动走预览，接口永不报错。
凭据默认只写入本地 data/credentials.json（不入库）。两种注入方式： ① 环境变量（首次注入，服务启动时自动导入存储）；② 账号助手（推荐）——在 api/music 目录运行：
node scripts/account-login.mjs --status 查看各平台凭据状态与有效期提示
node scripts/account-login.mjs --platform=xm 弹出浏览器 → 登录喜马拉雅网页账号一次
登录成功后自动导出 Cookie 入库（免 F12 抓包）
node scripts/account-login.mjs --platform=qingting --token=xxx --id=yyy [--refresh=zzz] [--device=ddd]
蜻蜓凭据填写一次（App 长期 token）
node scripts/account-login.mjs --platform=apple --token=xxx Apple Music 整曲解锁 token（预留）
node scripts/account-login.mjs --platform=kg --cookie=... 酷狗 Cookie（预留）
平台 解锁内容 自动续签现状（2026-09 实测） 蜻蜓FM 单集播放（QINGTING_ACCESS_TOKEN/QINGTING_ID） App 长期 token；oauth 续签端点已下线不可自动续，失效时重填 喜马拉雅 付费/VIP 集播放（XM_COOKIE） 网页 Cookie 无 refresh 协议；服务每 6h 巡检，失效提示重登一次 喜马拉雅 排行榜详情（XM_SIGN） 自动无头抓签缓存 5 分钟（需本机 Edge/Chrome） Apple Music 整曲播放（APPLE_MEDIA_USER_TOKEN） 预留（当前档位=30s 预览免凭据） (预留) KG_COOKIE / MG_TOKEN / SODA_COOKIE 后续按需启用
说明：服务启动时导入环境变量到存储，此后运行时读写 data/credentials.json（热加载无需重启）； 凭据守卫（api/music/src/credential_guard.js）启动时与每 6 小时巡检一次有效性，结果见启动日志与 /health（accounts 字段）。需要新增平台时在 src/accounts.js 登记字段与环境变量即可。