手里攒了一批自己早年在 SoundCloud 上发的 demo有的是手机直接录的有的是废弃工程里扒出来的半成品时间一长本地文件全丢了只剩平台上还挂着。想把这些东西捞回本地做归档顺手又想给一个独立音乐人的作品做离线备份结果试了市面上七八个图形界面的 SoundCloud 音乐下载工具没有一个能让我踏实跑完一批任务要么下载到第三十多首就莫名卡死要么下下来的文件时长对不上、尾部被截断要么标签全空、封面丢失几百个文件躺在文件夹里根本没法用。被折腾了两天之后我干脆自己从头搭了一条链路也就是后来我自己一直在用的这套 Soundcloud-Downloader 脚本集。它做的事情说起来不复杂给定一个 SoundCloud 曲目链接或者一个歌单链接把音频流完整地拉到本地写回标题、艺人、时长、封面这些元数据支持批量跑、支持中途断掉之后接着跑。但真正做起来坑几乎全藏在音频流这三个字后面——SoundCloud 并不是一个静态文件服务器它把音频拆成了转码列表、签名地址、分片清单这一整套东西你得先把这套分发结构吃透才谈得上稳定下载。这篇东西适合两类人看一类是懂点 Python、想自己维护一套归档工具的开发者另一类是纯粹想搞清楚一个在线音频平台的文件到底是怎么被组织出来的的技术爱好者。下面我按自己实际踩坑的顺序把整条链路拆开讲。1. 现成工具失灵的三个真实原因在动手写代码之前我花了半天时间把失败案例归了归类。搞清楚为什么现成的不好用比直接抄一份代码更有价值因为后面你会发现自己写的时候同样会撞上这三堵墙。1.1 图形化工具的通病把能跑一次当成了能一直跑绝大多数现成工具的骨架都是同一套从网页里抠出一个临时的资源地址然后直接对着这个地址发 GET 请求存成文件。这套逻辑在平台不改版的时候确实能跑但它有两个致命前提——第一这个地址在你开始下载的那一刻到下载结束之前一直有效第二这个地址返回的是一个完整的、可以直接播放的文件。现实是这两个前提都不稳。SoundCloud 的音频资源地址带有时效性签名一旦你排队的曲目多、单曲体积大排队到后面的任务拿着早就过期的地址去请求返回的就是一个 403 页面而很多工具会把 403 页面当成音频直接写进文件最后你得到一堆几 KB 的、用播放器打不开的文件。这类问题在单曲测试时完全看不出来一上批量就原形毕露。1.2 元数据被彻底丢弃导致文件下下来也没法用第二个问题是元数据。直接存字节流得到的只是一个裸音频容器里面没有任何标签信息。对于一个只有三五十首的曲库你还能靠文件名认出来但当你一次拉下来三百首、文件名还全是123456789.mp3这种 ID 命名的时候这批文件在本地曲库里就是一堆垃圾。我后来给自己定的标准是下载完成的文件必须做到双击能播放、音乐软件里能看到歌名和艺人、文件夹缩略图能看到封面。这三条听起来是常识但恰恰是最多工具做不到的地方因为它们只管搬运字节不管文件落到本地之后还能不能被识别。1.3 没有断点续传等于把网络波动放大成了灾难第三个问题最要命。假设你排了 200 首任务跑到第 157 首的时候网络抖了一下或者被限流了大部分工具的处理方式是整个进程退出或者更糟——继续往下跑把失败的任务静默跳过。前一种你要从头再来后一种你根本不知道自己漏了哪几首。我需要的是一套能记录哪些已经完成、哪些下到第几个分片的状态机。这个需求直接把方案定死了必须自己控制下载粒度而不能依赖某个库的一行代码下载整个文件。也就是从这一步开始我决定放弃 progressive 直链转向 HLS 分片这条路。2. SoundCloud 的音频分发结构链接为什么一刷新就失效要理解为什么地址会失效得先看清楚 SoundCloud 是怎么把一首曲目拆开喂给浏览器的。这一步是整个项目的地基我在这一层上反复推翻了两次设计。2.1 页面里那坨 hydration 数据才是真正的入口打开任意一个曲目页面右键查看源码你会看到一个script标签里面是一段 JSON挂在一个特定的全局变量下面。这段数据是服务端渲染时直接内联进去的里面包含了当前曲目的完整对象标题、时长、艺人、封面地址以及最关键的media字段。media下面有一个transcodings数组这是整条链路的起点。数组里通常不止一项每一项都描述了一种转码方式包含三个关键字段字段含义实操中的注意事项preset转码预设名如低码率 MP3、高码率 AAC 等不同曲目可用预设不一样老曲目可能只有一两种format容器与协议类型常见为progressive或hls这两个词决定了后面走完全不同的代码分支url获取实际媒体流的接口地址这个地址本身不带签名但它返回的内容带我第一次做的时候犯了个低级错误直接从页面 HTML 里用正则去抠.mp3结尾的字符串。结果抠出来的全是封面图的 CDN 地址因为真正的音频地址在这个页面里压根就不出现——它需要你用transcodings里的url再去请求一次才能拿到。这个认知差是很多新手卡住的第一关。2.2client_id的提取与失效判断请求transcodings里的那个url时必须带一个查询参数client_id。这个值不是固定的它藏在页面引用的某个打包后的 JS 文件里。提取思路很朴素先请求曲目页面把页面里所有script src...的地址抓出来然后逐个下载这些 JS 文件在文本里搜索client_id附近的赋值语句正则匹配出那一串 32 位的十六进制字符串。为了减少请求量可以只挑文件名里带公共运行时特征的那几个脚本去扫通常一两个文件就能命中。这里有个必须处理的现实问题client_id会轮换。轮换周期不固定可能几周也可能几天。所以架构上必须把它当成可失效的缓存而不是一次抓取永久使用。我的做法是把它连同抓取时间戳一起落盘同时在主流程里对 401 和 403 做统一拦截——一旦命中就清空缓存、重新抓一次、再重试当前请求最多重试两次。这个兜底逻辑让我后面省掉了无数次手动改配置的麻烦。注意抓取client_id的请求要带上一个正常的桌面浏览器 User-Agent。不带 UA 的请求有相当高的概率直接被挡回来返回一个空页面你会以为是正则写错了实际上是第一步就没拿到内容。2.3transcodings里的两条路决定了后面所有代码结构拿到transcodings数组之后第一件事是按format分流。progressive类型的项请求它的url会返回一个 JSON里面有一个url字段指向一个完整的、可以直接 GET 下来的音频文件通常是 MP3。这条路最短代码量最少但它有两个明显短板一是可用性不稳定部分曲目根本没有 progressive 项尤其是一些较新的上传二是码率通常不是最高的音质上会吃点亏。hls类型的项请求它的url返回的同样是一个 JSON但里面的url指向的是一个 m3u8 播放清单。这条路复杂得多但它几乎对所有曲目都可用而且通常能拿到更高码率的 AAC 流。我的策略是优先找最高码率的hls项找不到再退回progressive。这个优先级顺序不是拍脑袋定的而是实测下来的——HLS 那条路的资源可用率明显更高而且因为它是分片请求天然适合做断点续传。反过来如果你只走 progressive跑到一半发现某几首没有这个转码项整个批处理逻辑就得停下来单独处理异常体验很差。3. 两条下载链路的具体实现与取舍结构和入口搞明白之后真正写代码的时候会发现两条路的工程量差了一个数量级。这一节把两条路的实现细节分别摊开包括我实际写崩过两次的地方。3.1 progressive 直链最短路径和它的天花板progressive 的实现可以说非常简单请求 transcoding 地址拿到真实文件地址然后流式下载写盘。用aiohttp的话核心就是一个带iter_chunked的循环async def download_progressive(session, real_url, dest_path, chunk_size1 16): headers {User-Agent: UA, Referer: https://soundcloud.com/} async with session.get(real_url, headersheaders) as resp: resp.raise_for_status() total int(resp.headers.get(Content-Length, 0)) written 0 with open(dest_path, wb) as fp: async for chunk in resp.content.iter_chunked(chunk_size): fp.write(chunk) written len(chunk) if total and written ! total: raise IOError(f长度不符: 期望 {total}, 实际 {written})关键在最后那三行。我一开始没写这个长度校验结果出现过好几次文件下下来了、能播放、但尾部少了两秒的情况。原因是连接被服务端提前关闭时客户端不一定抛异常流就那么安静地结束了。加上Content-Length比对之后这类问题立刻变成了显式报错可以进入重试队列。这条路的另一个限制是它没有分片所以断点续传只能靠 HTTP 的Range请求头。理论上可行但实际测试下来服务端对Range的支持并不总是可靠有时候会忽略这个头直接返回 200 和完整内容。所以我的最终结论是progressive 只作为兜底方案不做断点续传失败就整首重下真正承担批量任务的是 HLS。3.2 HLS 分片一份 m3u8 里的 byte-range 玄机第一次拿到 m3u8 内容的时候我是懵的。按理说 HLS 应该是一堆独立的.ts分片文件但 SoundCloud 返回的清单长这样简化过#EXTM3U #EXT-X-VERSION:6 #EXT-X-TARGETDURATION:10 #EXT-X-PLAYLIST-TYPE:VOD #EXT-X-MAP:URIhttps://.../aac.m4a?range0-8191 #EXTINF:10.0, https://.../aac.m4a?range8192-163839 #EXTINF:10.0, https://.../aac.m4a?range163840-319487所有分片指向的是同一个文件路径区别只在查询参数里的range。也就是说这是一个用 fMP4 封装的单文件被切成了若干字节区间。EXT-X-MAP那一行是初始化段里面包含 moov box是解码必需的头信息。这个结构带来两个直接影响。第一你不能用一个简单的 HTTPRange头去下第二个分片必须老老实实按清单里给出的区间去请求因为服务端校验的是 URL 里的range参数而不是请求头。第二合并的时候顺序不能乱第一个字节必须是EXT-X-MAP那一段的内容否则整个文件解不出来。解析清单的代码本身很短但有两个细节容易漏import re RANGE_RE re.compile(rrange(\d)-(\d)) def parse_playlist(text): init_url, segments None, [] for line in text.splitlines(): line line.strip() if not line: continue if line.startswith(#EXT-X-MAP): m re.search(rURI([^]), line) if m: init_url m.group(1) elif not line.startswith(#): segments.append(line) return init_url, segments第一个坑是空行和以#开头的注释行必须过滤掉不加判断的话会把#EXTINF当成 URL 去请求。第二个坑是EXT-X-MAP的 URI 在属性列表里需要用引号匹配而不能简单地按切分因为属性串里可能还有别的键值对。3.3 分片合并的两条技术路线把分片都拿回来之后怎么合并成一个可播放的文件有两条路。第一条是纯字节拼接按顺序把初始化段和所有分片的bytes依次写进同一个文件。这条路简单、快、无依赖得到的文件就是一个完整的 fMP4 容器VLC 和大部分播放器能直接放。缺点是这个容器的索引信息可能不够规整某些老播放器或者某些移动端会有兼容问题。第二条是先拼后转拼完之后调一次 ffmpeg 做流拷贝重新封装成标准的 M4A 或者转成 MP3。ffmpeg -hide_banner -loglevel error -y \ -i temp_concat.m4a \ -c:a copy -movflags faststart \ output.m4a-c:a copy表示不重新编码只重新封装所以速度极快几乎不消耗 CPU音质也无损。faststart会把索引挪到文件头部方便边下边播的场景。我最终的方案是默认走第一条路如果检测到输出文件在某些播放器上有问题再兜底跑第二条。判断有没有问题的土办法是用 ffprobe 读一下时长和曲目元数据里的时长比对误差超过 1.5 秒就触发重新封装。这个阈值是试出来的——正常误差在 0.1 到 0.3 秒之间一旦超过 1 秒基本就是容器结构出了岔子。提示拼接临时文件的时候一定要用wb模式一次性打开、按顺序写完全部片段再关闭。我早期图省事用ab模式反复打开追加结果在某次进程被中断后残留了一个半截文件下次运行时又往后追加了一遍最终文件时长翻倍排查了很久才发现是模式选错了。4. 让文件在本地曲库里真正可用音频到手只是完成了一半。一个只有字节、没有标签的文件扔进任何音乐管理软件里都是一条未知艺人 - 未知曲目。这一节讲元数据这块我是怎么补齐的。4.1 MP3 的 ID3 与 M4A 的 ilst两套完全不同的标签体系MP3 用的是 ID3v2 标签挂在文件头或者尾部v2.4 支持追加。M4A 用的是 MP4 容器里的ilstatom是一个嵌套的树状结构。这两套东西结构完全不同不能混着写。Python 生态里处理这件事最省心的库是mutagen它对两种格式都提供了统一的高层接口。写入 M4A 的典型流程是这样from mutagen.mp4 import MP4, MP4Cover audio MP4(path) audio[\xa9nam] [title] # 标题 audio[\xa9ART] [artist] # 艺人 audio[\xa9alb] [album] # 专辑 audio[\xa9day] [publish_date] # 年份 audio[\xa9gen] [genre] # 流派 audio[trkn] [(1, total)] # 音轨号 / 总数 audio.save()那几个\xa9开头的键名是 MP4 规范里的固定标识\xa9在 Latin-1 里就是版权符号所以写成\xa9nam而不是nam。这一点非常容易写错而且写错了不会报错只会静默地写不进去你在播放器里看到的还是空标签。我第一次就是漏了\xa9前缀白白排查了半小时。MP3 那边则是另一套键名from mutagen.id3 import ID3, TIT2, TPE1, TALB, TDRC, APIC tags ID3() tags.add(TIT2(encoding3, texttitle)) tags.add(TPE1(encoding3, textartist)) tags.add(TALB(encoding3, textalbum)) tags.add(TDRC(encoding3, textstr(year))) tags.save(mp3_path)encoding3表示 UTF-8这个参数不能省省了默认按 Latin-1 处理中文标题直接乱码。这是我踩过的最典型的一个坑而且症状很有欺骗性——文件能播放播放器界面上显示一行问号你以为是播放器字体问题实际上是写入时就编错了码。4.2 封面尺寸的一个小技巧SoundCloud 返回的artwork_url默认是缩略图尺寸通常是一百多像素见方直接嵌进去在高分屏上糊得很明显。这个地址里有一个尺寸标识字段把它替换成更大的尺寸就能拿到高清图。常见的可选尺寸从几十像素到一千像素都有我一般用接近 500 的那一档兼顾清晰度和文件体积。封面下载下来之后格式判断有个细节artwork_url路径末尾虽然经常是.jpg但实际返回的内容类型可能是image/png尤其是用户自己上传的透明背景图。所以写入时要按响应的Content-Type来决定MP4Cover的imageformat参数而不是按扩展名猜。写错了的结果是封面在某些软件里能显示、在某些软件里一片灰很难定位。from mutagen.mp4 import MP4Cover cover MP4Cover(img_bytes, imageformatMP4Cover.FORMAT_JPEG) # 或 FORMAT_PNG audio[covr] [cover]4.3 文件命名别等到几百个文件堆一起才后悔命名规则我在第一批任务跑完之后就改了三次。最终定下来的是一个兼顾排序和可读性的格式{艺人}/{年份} - {专辑}/{音轨号:02d} - {标题}.m4a几个具体的取舍。艺人名和专辑名里会出现斜杠、冒号、问号这些在文件系统里非法的字符必须做一次白名单过滤把非法字符替换掉同时把连续空格压成一个。控制单个路径段的长度上限在 120 字符左右超长的用标题前若干字符加曲目 ID 兜底避免某些文件系统对路径总长有限制。曲目 ID 一定要保留在兜底名里因为它是唯一的能让你在出问题时反查回原页面。另外我习惯在下载的同时往曲目目录里写一个info.json把原始元数据整份存下来。这东西平时用不上但当你需要重新整理曲库、或者想批量修改标签格式的时候它就是唯一的可信来源——因为音频文件里的标签已经被你改过好几轮了。5. 批量下载的工程化控制单首下载能跑通之后真正的挑战才开始。批量任务和单任务完全是两个物种前者要考虑并发、限流、状态持久化和失败重试任何一环处理不好都会让整批任务的可用性大打折扣。5.1 并发数为什么我把默认值定在 4第一版我图快直接把并发拉到 20结果跑了两百多首之后开始大面积失败全是被限流打回来的。后来降到 8还是有零星失败。最终稳定在 4连续跑过几次接近一千首的任务失败率控制在个位数。这个数字背后有它的道理。每个下载任务实际上会产生两类请求分片请求和元数据请求。HLS 的分片数量通常和曲目时长成正比一首五分钟的曲子大概有三十个分片。如果你的并发是 20而每首曲子内部又同时抓几个分片瞬时并发会轻松突破一百触发限流几乎是必然的。所以我的实现里用了两层控制外层用一个全局信号量限制同时进行的曲目数量内层对单曲的分片请求也做了串行化或者小并发处理。import asyncio track_sem asyncio.Semaphore(4) async def handle_track(task): async with track_sem: return await download_one(task)分片层面我选择串行。听起来慢但实测下来整体吞吐并不差因为瓶颈在网络带宽和限流上而不是在并发度上。串行反而让限流触发概率大幅下降重试次数变少总耗时接近甚至更优。5.2 403 与 429 的区别对待这两种状态码看起来都是被拒但处理方式完全不同混为一谈会让逻辑变复杂。403通常意味着签名过期或者client_id失效。这类错误重试同一个请求没有意义必须刷新凭据后重新生成地址。我的处理是捕获 403 之后触发一次client_id重抓然后从头重新解析这首曲目的transcodings拿到新地址再试。429则是限流意思是你现在太频繁了等会儿再来。这类错误需要的是退避而且最好是带随机抖动的指数退避避免多个任务在同一时刻齐刷刷地重试再次撞在一起。async def request_with_backoff(session, url, max_retries5): for attempt in range(max_retries): resp await session.get(url, headersHEADERS) if resp.status 429: wait (2 ** attempt) random.uniform(0, 1.5) await asyncio.sleep(wait) continue if resp.status 403: await refresh_client_id() raise CredentialExpired(url) return resp raise TooManyRetries(url)那个random.uniform(0, 1.5)的抖动非常关键。去掉它之后我观察到大量任务会在同一秒集中重试然后集体再次被拒形成一种规律性的失败波峰。加上抖动之后重试请求被摊平到了一个时间窗口里成功率明显提升。5.3 状态文件断点续传的核心状态管理的设计目标只有一条任何时刻按 CtrlC重新启动后能准确知道该从哪儿继续。我用的是一份 JSON 状态文件结构大致是任务 ID 到状态的映射{ track:1029384: { status: partial, title: ..., done_segments: 17, total_segments: 31, init_saved: true, updated_at: 2024-01-01T12:00:00 } }几个设计上的取舍值得说一下。第一状态用已完成分片数而不是已完成字节数来记录因为分片的边界是清单里明确给出的按分片粒度恢复不会出现半截分片的问题而按字节记录就得处理分片内部偏移复杂且容易出错。第二每完成一个分片就落盘一次状态而不是整首完成才写代价是多了些 IO但换来的是断点精度控制在单个分片以内。第三状态文件写入用写临时文件 原子替换的方式避免进程在写文件过程中被杀导致状态文件损坏、整个任务列表作废。分片本身也单独存盘放在一个临时目录里命名用{track_id}_{index:04d}.part。恢复的时候先检查这些文件是否存在存在就跳过对应的网络请求。这套机制在实际用起来之后最大的价值不是省流量而是让我可以在网络状况不好的时候分多次把一批任务跑完每次跑十几分钟累计起来一样能完成。6. 排查实录几个折腾了很久的失败场景前面讲的是设计这里讲的是实际出问题时的样子。这几个案例我都完整记录过排查过程因为它们的症状都很有欺骗性第一次遇到基本不可能一次定位。6.1 时长对不上从文件损坏追到初始化段缺失最早的症状是下载完成的文件能播放但播放器显示的时长比实际短而且拖进度条到最后会卡住。用 ffprobe 一看报告的时长只有实际的一半左右。我最初的判断是分片没下全于是把每个分片的字节数和清单里的区间长度逐个比对全都对得上。接着怀疑是合并顺序错了重新检查了一遍拼接逻辑也没问题。真正的突破点是拿一个已知正常的文件和出问题的文件做二进制对比。正常的文件开头有一段明显的ftyp和moov结构出问题的文件开头直接就是moof。这说明初始化段没有被写进去。回头看代码问题出在解析清单时EXT-X-MAP那一行是带属性列表的我的正则写得太窄只匹配了不带引号的情况导致init_url一直是None而后面拼接时对None做了静默跳过——因为我在写的时候用了if init_url:这种防御性判断反而把错误掩盖掉了。修完之后我加了一条断言拼接开始前如果init_url为空就直接抛异常绝不静默继续。这条规则后来帮我挡住了好几次类似的隐性失败。6.2 爆音与杂音分片错序的典型症状另一个案例更隐蔽。文件时长完全正确播放也正常但在某些位置会出现很短的咔声。这种问题在整轨试听时很容易被忽略是我用耳机逐段听的时候才发现的。原因是分片的写入顺序和清单顺序不一致。我早期为了提速用了asyncio.gather并发抓分片然后用一个共享的写文件句柄边抓边写。并发返回的顺序是不确定的写进去的字节自然就乱了。因为 fMP4 的分片边界对齐得比较好乱序之后大部分数据仍能解码但衔接处会出现采样不连续听起来就是一声脆响。修法很简单并发抓取可以保留但必须先把所有分片按索引放进一个字典等全部完成后再按顺序写盘。或者更省内存的做法是抓完立即按索引命名存到临时目录最后再统一顺序拼接。我选了后者因为批量任务时内存占用更低。6.3 其他几个高频问题速查除了上面两个大头还有一些零碎但高频的问题整理成一张表方便对照现象根因处理方式单个分片请求一直超时该区间的地址已过期重新解析清单拿新地址不要重试旧地址分片全部成功但拼接失败临时目录磁盘空间不足下载前检查可用空间按曲目总大小预留标签写入报错但文件能放容器实际格式与扩展名不一致用 ffprobe 探测真实容器按结果选写入器封面在某些播放器不显示图片格式标识与实际不符按响应的 Content-Type 决定 imageformat批量跑一半进程静默退出未捕获的异常在任务协程里抛出每个任务包一层 try/except异常记入失败队列那张表里最后一条是我用血换来的。asyncio里如果某个任务协程抛了未捕获异常而你又没有正确地await或者收集它的结果这个异常可能就悄无声息地消失了主流程继续往下跑你只会发现怎么少了几首。所以现在我的任务调度器里每一个任务的执行都包在一层统一的异常处理里失败信息连同原始地址一起写进失败队列最后统一报告。7. 使用边界哪些内容该下哪些不该碰技术上跑通之后还有一个绕不开的问题必须说清楚因为这决定了这套工具是自用归档还是越界使用。7.1 平台侧的下载许可与授权协议SoundCloud 上并不是所有曲目都允许下载。曲目对象里有一个表示下载权限的字段创作者在发布时可以打开或关闭它。打开之后页面上会出现下载按钮这代表创作者明确允许听众把文件拿走。对于这类曲目通过接口拿文件是完全符合平台设计意图的行为。另一类是标注了开放授权协议的曲目。这类作品的权利人已经通过协议明确授予了复制和传播的许可只要遵守协议里的署名等条件下载和再使用都是被允许的。我在做归档的时候会优先识别这两类把它们和普通曲目分开存放并在info.json里记录授权信息。至于那些既没开下载权限、也没标注开放协议的曲目正确的做法是老老实实通过平台的收藏、歌单功能去管理而不是绕开限制把文件拿走。这一点我在代码里做了硬性拦截解析元数据时先检查下载许可标志不满足条件就直接跳过并记录原因不进入下载队列。7.2 个人离线备份的合理尺度即便是允许下载的曲目使用方式也有边界。我给自己划的线是只下载我自己上传的作品以及明确授权下载的他人作品下载后仅用于个人离线收听和本地归档不再分发。这条线看起来保守但它让整个工具的使用场景非常清晰——它是一个个人资料管理工具而不是一个内容获取工具。落到代码层面我在 CLI 入口加了一个显式的确认环节批量任务开始前会把将要下载的曲目列表和它们的授权状态打印出来需要手动确认才会继续。这个设计一开始只是为了调试方便后来发现它其实是个很好的自我约束机制当你看到列表里混进了不该下的东西时会在按下回车之前就停下来。8. 最后一点实操体会这套东西我从最初的一百多行脚本慢慢长到现在带状态机、带并发控制、带元数据管道的完整工具中间重构过三次。如果让我给准备动手的人一句建议那会是先把单首曲目的完整链路——从页面解析到分片合并再到标签写入——彻底跑通并且验证过再去碰批量。因为批量只是把单曲逻辑放进循环真正难的部分全在单曲链路里。我见过太多人一上来就搭异步调度框架、搭状态持久化结果单曲下载本身就有隐性 bug等到批量跑出问题的时候根本分不清是调度层的锅还是下载层的锅排查成本翻好几倍。另外这套链路高度依赖平台当前的接口形态任何一个环节的字段命名、清单结构、鉴权方式发生变化代码都得跟着调整。所以我在实现时刻意把解析和下载拆成了两层中间用一个数据结构衔接。这样接口一变我只需要改解析层下载层和元数据层完全不用动。这个分层在第一年里就救了我不下五次。单曲体积方面也可以给个参考一首五分钟左右的曲目高码率 AAC 流一般在 8 到 12 MB 之间分片数量在 25 到 40 个之间。按这个量级估算磁盘和带宽比凭感觉拍数字靠谱得多。我一开始按MP3 一首 10 MB估结果遇到一批较长的现场录音单曲接近 40 MB硬盘规划直接失准后来改成按曲目时长动态估算才稳定下来。 
长河君 · 2026/11/2 7:24:16 · 阅读 1.2k SoundCloud批量下载：HLS分片、断点续传与元数据写入
手里攒了一批自己早年在 SoundCloud 上发的 demo有的是手机直接录的有的是废弃工程里扒出来的半成品时间一长本地文件全丢了只剩平台上还挂着。想把这些东西捞回本地做归档顺手又想给一个独立音乐人的作品做离线备份结果试了市面上七八个图形界面的 SoundCloud 音乐下载工具没有一个能让我踏实跑完一批任务要么下载到第三十多首就莫名卡死要么下下来的文件时长对不上、尾部被截断要么标签全空、封面丢失几百个文件躺在文件夹里根本没法用。被折腾了两天之后我干脆自己从头搭了一条链路也就是后来我自己一直在用的这套 Soundcloud-Downloader 脚本集。它做的事情说起来不复杂给定一个 SoundCloud 曲目链接或者一个歌单链接把音频流完整地拉到本地写回标题、艺人、时长、封面这些元数据支持批量跑、支持中途断掉之后接着跑。但真正做起来坑几乎全藏在音频流这三个字后面——SoundCloud 并不是一个静态文件服务器它把音频拆成了转码列表、签名地址、分片清单这一整套东西你得先把这套分发结构吃透才谈得上稳定下载。这篇东西适合两类人看一类是懂点 Python、想自己维护一套归档工具的开发者另一类是纯粹想搞清楚一个在线音频平台的文件到底是怎么被组织出来的的技术爱好者。下面我按自己实际踩坑的顺序把整条链路拆开讲。1. 现成工具失灵的三个真实原因在动手写代码之前我花了半天时间把失败案例归了归类。搞清楚为什么现成的不好用比直接抄一份代码更有价值因为后面你会发现自己写的时候同样会撞上这三堵墙。1.1 图形化工具的通病把能跑一次当成了能一直跑绝大多数现成工具的骨架都是同一套从网页里抠出一个临时的资源地址然后直接对着这个地址发 GET 请求存成文件。这套逻辑在平台不改版的时候确实能跑但它有两个致命前提——第一这个地址在你开始下载的那一刻到下载结束之前一直有效第二这个地址返回的是一个完整的、可以直接播放的文件。现实是这两个前提都不稳。SoundCloud 的音频资源地址带有时效性签名一旦你排队的曲目多、单曲体积大排队到后面的任务拿着早就过期的地址去请求返回的就是一个 403 页面而很多工具会把 403 页面当成音频直接写进文件最后你得到一堆几 KB 的、用播放器打不开的文件。这类问题在单曲测试时完全看不出来一上批量就原形毕露。1.2 元数据被彻底丢弃导致文件下下来也没法用第二个问题是元数据。直接存字节流得到的只是一个裸音频容器里面没有任何标签信息。对于一个只有三五十首的曲库你还能靠文件名认出来但当你一次拉下来三百首、文件名还全是123456789.mp3这种 ID 命名的时候这批文件在本地曲库里就是一堆垃圾。我后来给自己定的标准是下载完成的文件必须做到双击能播放、音乐软件里能看到歌名和艺人、文件夹缩略图能看到封面。这三条听起来是常识但恰恰是最多工具做不到的地方因为它们只管搬运字节不管文件落到本地之后还能不能被识别。1.3 没有断点续传等于把网络波动放大成了灾难第三个问题最要命。假设你排了 200 首任务跑到第 157 首的时候网络抖了一下或者被限流了大部分工具的处理方式是整个进程退出或者更糟——继续往下跑把失败的任务静默跳过。前一种你要从头再来后一种你根本不知道自己漏了哪几首。我需要的是一套能记录哪些已经完成、哪些下到第几个分片的状态机。这个需求直接把方案定死了必须自己控制下载粒度而不能依赖某个库的一行代码下载整个文件。也就是从这一步开始我决定放弃 progressive 直链转向 HLS 分片这条路。2. SoundCloud 的音频分发结构链接为什么一刷新就失效要理解为什么地址会失效得先看清楚 SoundCloud 是怎么把一首曲目拆开喂给浏览器的。这一步是整个项目的地基我在这一层上反复推翻了两次设计。2.1 页面里那坨 hydration 数据才是真正的入口打开任意一个曲目页面右键查看源码你会看到一个script标签里面是一段 JSON挂在一个特定的全局变量下面。这段数据是服务端渲染时直接内联进去的里面包含了当前曲目的完整对象标题、时长、艺人、封面地址以及最关键的media字段。media下面有一个transcodings数组这是整条链路的起点。数组里通常不止一项每一项都描述了一种转码方式包含三个关键字段字段含义实操中的注意事项preset转码预设名如低码率 MP3、高码率 AAC 等不同曲目可用预设不一样老曲目可能只有一两种format容器与协议类型常见为progressive或hls这两个词决定了后面走完全不同的代码分支url获取实际媒体流的接口地址这个地址本身不带签名但它返回的内容带我第一次做的时候犯了个低级错误直接从页面 HTML 里用正则去抠.mp3结尾的字符串。结果抠出来的全是封面图的 CDN 地址因为真正的音频地址在这个页面里压根就不出现——它需要你用transcodings里的url再去请求一次才能拿到。这个认知差是很多新手卡住的第一关。2.2client_id的提取与失效判断请求transcodings里的那个url时必须带一个查询参数client_id。这个值不是固定的它藏在页面引用的某个打包后的 JS 文件里。提取思路很朴素先请求曲目页面把页面里所有script src...的地址抓出来然后逐个下载这些 JS 文件在文本里搜索client_id附近的赋值语句正则匹配出那一串 32 位的十六进制字符串。为了减少请求量可以只挑文件名里带公共运行时特征的那几个脚本去扫通常一两个文件就能命中。这里有个必须处理的现实问题client_id会轮换。轮换周期不固定可能几周也可能几天。所以架构上必须把它当成可失效的缓存而不是一次抓取永久使用。我的做法是把它连同抓取时间戳一起落盘同时在主流程里对 401 和 403 做统一拦截——一旦命中就清空缓存、重新抓一次、再重试当前请求最多重试两次。这个兜底逻辑让我后面省掉了无数次手动改配置的麻烦。注意抓取client_id的请求要带上一个正常的桌面浏览器 User-Agent。不带 UA 的请求有相当高的概率直接被挡回来返回一个空页面你会以为是正则写错了实际上是第一步就没拿到内容。2.3transcodings里的两条路决定了后面所有代码结构拿到transcodings数组之后第一件事是按format分流。progressive类型的项请求它的url会返回一个 JSON里面有一个url字段指向一个完整的、可以直接 GET 下来的音频文件通常是 MP3。这条路最短代码量最少但它有两个明显短板一是可用性不稳定部分曲目根本没有 progressive 项尤其是一些较新的上传二是码率通常不是最高的音质上会吃点亏。hls类型的项请求它的url返回的同样是一个 JSON但里面的url指向的是一个 m3u8 播放清单。这条路复杂得多但它几乎对所有曲目都可用而且通常能拿到更高码率的 AAC 流。我的策略是优先找最高码率的hls项找不到再退回progressive。这个优先级顺序不是拍脑袋定的而是实测下来的——HLS 那条路的资源可用率明显更高而且因为它是分片请求天然适合做断点续传。反过来如果你只走 progressive跑到一半发现某几首没有这个转码项整个批处理逻辑就得停下来单独处理异常体验很差。3. 两条下载链路的具体实现与取舍结构和入口搞明白之后真正写代码的时候会发现两条路的工程量差了一个数量级。这一节把两条路的实现细节分别摊开包括我实际写崩过两次的地方。3.1 progressive 直链最短路径和它的天花板progressive 的实现可以说非常简单请求 transcoding 地址拿到真实文件地址然后流式下载写盘。用aiohttp的话核心就是一个带iter_chunked的循环async def download_progressive(session, real_url, dest_path, chunk_size1 16): headers {User-Agent: UA, Referer: https://soundcloud.com/} async with session.get(real_url, headersheaders) as resp: resp.raise_for_status() total int(resp.headers.get(Content-Length, 0)) written 0 with open(dest_path, wb) as fp: async for chunk in resp.content.iter_chunked(chunk_size): fp.write(chunk) written len(chunk) if total and written ! total: raise IOError(f长度不符: 期望 {total}, 实际 {written})关键在最后那三行。我一开始没写这个长度校验结果出现过好几次文件下下来了、能播放、但尾部少了两秒的情况。原因是连接被服务端提前关闭时客户端不一定抛异常流就那么安静地结束了。加上Content-Length比对之后这类问题立刻变成了显式报错可以进入重试队列。这条路的另一个限制是它没有分片所以断点续传只能靠 HTTP 的Range请求头。理论上可行但实际测试下来服务端对Range的支持并不总是可靠有时候会忽略这个头直接返回 200 和完整内容。所以我的最终结论是progressive 只作为兜底方案不做断点续传失败就整首重下真正承担批量任务的是 HLS。3.2 HLS 分片一份 m3u8 里的 byte-range 玄机第一次拿到 m3u8 内容的时候我是懵的。按理说 HLS 应该是一堆独立的.ts分片文件但 SoundCloud 返回的清单长这样简化过#EXTM3U #EXT-X-VERSION:6 #EXT-X-TARGETDURATION:10 #EXT-X-PLAYLIST-TYPE:VOD #EXT-X-MAP:URIhttps://.../aac.m4a?range0-8191 #EXTINF:10.0, https://.../aac.m4a?range8192-163839 #EXTINF:10.0, https://.../aac.m4a?range163840-319487所有分片指向的是同一个文件路径区别只在查询参数里的range。也就是说这是一个用 fMP4 封装的单文件被切成了若干字节区间。EXT-X-MAP那一行是初始化段里面包含 moov box是解码必需的头信息。这个结构带来两个直接影响。第一你不能用一个简单的 HTTPRange头去下第二个分片必须老老实实按清单里给出的区间去请求因为服务端校验的是 URL 里的range参数而不是请求头。第二合并的时候顺序不能乱第一个字节必须是EXT-X-MAP那一段的内容否则整个文件解不出来。解析清单的代码本身很短但有两个细节容易漏import re RANGE_RE re.compile(rrange(\d)-(\d)) def parse_playlist(text): init_url, segments None, [] for line in text.splitlines(): line line.strip() if not line: continue if line.startswith(#EXT-X-MAP): m re.search(rURI([^]), line) if m: init_url m.group(1) elif not line.startswith(#): segments.append(line) return init_url, segments第一个坑是空行和以#开头的注释行必须过滤掉不加判断的话会把#EXTINF当成 URL 去请求。第二个坑是EXT-X-MAP的 URI 在属性列表里需要用引号匹配而不能简单地按切分因为属性串里可能还有别的键值对。3.3 分片合并的两条技术路线把分片都拿回来之后怎么合并成一个可播放的文件有两条路。第一条是纯字节拼接按顺序把初始化段和所有分片的bytes依次写进同一个文件。这条路简单、快、无依赖得到的文件就是一个完整的 fMP4 容器VLC 和大部分播放器能直接放。缺点是这个容器的索引信息可能不够规整某些老播放器或者某些移动端会有兼容问题。第二条是先拼后转拼完之后调一次 ffmpeg 做流拷贝重新封装成标准的 M4A 或者转成 MP3。ffmpeg -hide_banner -loglevel error -y \ -i temp_concat.m4a \ -c:a copy -movflags faststart \ output.m4a-c:a copy表示不重新编码只重新封装所以速度极快几乎不消耗 CPU音质也无损。faststart会把索引挪到文件头部方便边下边播的场景。我最终的方案是默认走第一条路如果检测到输出文件在某些播放器上有问题再兜底跑第二条。判断有没有问题的土办法是用 ffprobe 读一下时长和曲目元数据里的时长比对误差超过 1.5 秒就触发重新封装。这个阈值是试出来的——正常误差在 0.1 到 0.3 秒之间一旦超过 1 秒基本就是容器结构出了岔子。提示拼接临时文件的时候一定要用wb模式一次性打开、按顺序写完全部片段再关闭。我早期图省事用ab模式反复打开追加结果在某次进程被中断后残留了一个半截文件下次运行时又往后追加了一遍最终文件时长翻倍排查了很久才发现是模式选错了。4. 让文件在本地曲库里真正可用音频到手只是完成了一半。一个只有字节、没有标签的文件扔进任何音乐管理软件里都是一条未知艺人 - 未知曲目。这一节讲元数据这块我是怎么补齐的。4.1 MP3 的 ID3 与 M4A 的 ilst两套完全不同的标签体系MP3 用的是 ID3v2 标签挂在文件头或者尾部v2.4 支持追加。M4A 用的是 MP4 容器里的ilstatom是一个嵌套的树状结构。这两套东西结构完全不同不能混着写。Python 生态里处理这件事最省心的库是mutagen它对两种格式都提供了统一的高层接口。写入 M4A 的典型流程是这样from mutagen.mp4 import MP4, MP4Cover audio MP4(path) audio[\xa9nam] [title] # 标题 audio[\xa9ART] [artist] # 艺人 audio[\xa9alb] [album] # 专辑 audio[\xa9day] [publish_date] # 年份 audio[\xa9gen] [genre] # 流派 audio[trkn] [(1, total)] # 音轨号 / 总数 audio.save()那几个\xa9开头的键名是 MP4 规范里的固定标识\xa9在 Latin-1 里就是版权符号所以写成\xa9nam而不是nam。这一点非常容易写错而且写错了不会报错只会静默地写不进去你在播放器里看到的还是空标签。我第一次就是漏了\xa9前缀白白排查了半小时。MP3 那边则是另一套键名from mutagen.id3 import ID3, TIT2, TPE1, TALB, TDRC, APIC tags ID3() tags.add(TIT2(encoding3, texttitle)) tags.add(TPE1(encoding3, textartist)) tags.add(TALB(encoding3, textalbum)) tags.add(TDRC(encoding3, textstr(year))) tags.save(mp3_path)encoding3表示 UTF-8这个参数不能省省了默认按 Latin-1 处理中文标题直接乱码。这是我踩过的最典型的一个坑而且症状很有欺骗性——文件能播放播放器界面上显示一行问号你以为是播放器字体问题实际上是写入时就编错了码。4.2 封面尺寸的一个小技巧SoundCloud 返回的artwork_url默认是缩略图尺寸通常是一百多像素见方直接嵌进去在高分屏上糊得很明显。这个地址里有一个尺寸标识字段把它替换成更大的尺寸就能拿到高清图。常见的可选尺寸从几十像素到一千像素都有我一般用接近 500 的那一档兼顾清晰度和文件体积。封面下载下来之后格式判断有个细节artwork_url路径末尾虽然经常是.jpg但实际返回的内容类型可能是image/png尤其是用户自己上传的透明背景图。所以写入时要按响应的Content-Type来决定MP4Cover的imageformat参数而不是按扩展名猜。写错了的结果是封面在某些软件里能显示、在某些软件里一片灰很难定位。from mutagen.mp4 import MP4Cover cover MP4Cover(img_bytes, imageformatMP4Cover.FORMAT_JPEG) # 或 FORMAT_PNG audio[covr] [cover]4.3 文件命名别等到几百个文件堆一起才后悔命名规则我在第一批任务跑完之后就改了三次。最终定下来的是一个兼顾排序和可读性的格式{艺人}/{年份} - {专辑}/{音轨号:02d} - {标题}.m4a几个具体的取舍。艺人名和专辑名里会出现斜杠、冒号、问号这些在文件系统里非法的字符必须做一次白名单过滤把非法字符替换掉同时把连续空格压成一个。控制单个路径段的长度上限在 120 字符左右超长的用标题前若干字符加曲目 ID 兜底避免某些文件系统对路径总长有限制。曲目 ID 一定要保留在兜底名里因为它是唯一的能让你在出问题时反查回原页面。另外我习惯在下载的同时往曲目目录里写一个info.json把原始元数据整份存下来。这东西平时用不上但当你需要重新整理曲库、或者想批量修改标签格式的时候它就是唯一的可信来源——因为音频文件里的标签已经被你改过好几轮了。5. 批量下载的工程化控制单首下载能跑通之后真正的挑战才开始。批量任务和单任务完全是两个物种前者要考虑并发、限流、状态持久化和失败重试任何一环处理不好都会让整批任务的可用性大打折扣。5.1 并发数为什么我把默认值定在 4第一版我图快直接把并发拉到 20结果跑了两百多首之后开始大面积失败全是被限流打回来的。后来降到 8还是有零星失败。最终稳定在 4连续跑过几次接近一千首的任务失败率控制在个位数。这个数字背后有它的道理。每个下载任务实际上会产生两类请求分片请求和元数据请求。HLS 的分片数量通常和曲目时长成正比一首五分钟的曲子大概有三十个分片。如果你的并发是 20而每首曲子内部又同时抓几个分片瞬时并发会轻松突破一百触发限流几乎是必然的。所以我的实现里用了两层控制外层用一个全局信号量限制同时进行的曲目数量内层对单曲的分片请求也做了串行化或者小并发处理。import asyncio track_sem asyncio.Semaphore(4) async def handle_track(task): async with track_sem: return await download_one(task)分片层面我选择串行。听起来慢但实测下来整体吞吐并不差因为瓶颈在网络带宽和限流上而不是在并发度上。串行反而让限流触发概率大幅下降重试次数变少总耗时接近甚至更优。5.2 403 与 429 的区别对待这两种状态码看起来都是被拒但处理方式完全不同混为一谈会让逻辑变复杂。403通常意味着签名过期或者client_id失效。这类错误重试同一个请求没有意义必须刷新凭据后重新生成地址。我的处理是捕获 403 之后触发一次client_id重抓然后从头重新解析这首曲目的transcodings拿到新地址再试。429则是限流意思是你现在太频繁了等会儿再来。这类错误需要的是退避而且最好是带随机抖动的指数退避避免多个任务在同一时刻齐刷刷地重试再次撞在一起。async def request_with_backoff(session, url, max_retries5): for attempt in range(max_retries): resp await session.get(url, headersHEADERS) if resp.status 429: wait (2 ** attempt) random.uniform(0, 1.5) await asyncio.sleep(wait) continue if resp.status 403: await refresh_client_id() raise CredentialExpired(url) return resp raise TooManyRetries(url)那个random.uniform(0, 1.5)的抖动非常关键。去掉它之后我观察到大量任务会在同一秒集中重试然后集体再次被拒形成一种规律性的失败波峰。加上抖动之后重试请求被摊平到了一个时间窗口里成功率明显提升。5.3 状态文件断点续传的核心状态管理的设计目标只有一条任何时刻按 CtrlC重新启动后能准确知道该从哪儿继续。我用的是一份 JSON 状态文件结构大致是任务 ID 到状态的映射{ track:1029384: { status: partial, title: ..., done_segments: 17, total_segments: 31, init_saved: true, updated_at: 2024-01-01T12:00:00 } }几个设计上的取舍值得说一下。第一状态用已完成分片数而不是已完成字节数来记录因为分片的边界是清单里明确给出的按分片粒度恢复不会出现半截分片的问题而按字节记录就得处理分片内部偏移复杂且容易出错。第二每完成一个分片就落盘一次状态而不是整首完成才写代价是多了些 IO但换来的是断点精度控制在单个分片以内。第三状态文件写入用写临时文件 原子替换的方式避免进程在写文件过程中被杀导致状态文件损坏、整个任务列表作废。分片本身也单独存盘放在一个临时目录里命名用{track_id}_{index:04d}.part。恢复的时候先检查这些文件是否存在存在就跳过对应的网络请求。这套机制在实际用起来之后最大的价值不是省流量而是让我可以在网络状况不好的时候分多次把一批任务跑完每次跑十几分钟累计起来一样能完成。6. 排查实录几个折腾了很久的失败场景前面讲的是设计这里讲的是实际出问题时的样子。这几个案例我都完整记录过排查过程因为它们的症状都很有欺骗性第一次遇到基本不可能一次定位。6.1 时长对不上从文件损坏追到初始化段缺失最早的症状是下载完成的文件能播放但播放器显示的时长比实际短而且拖进度条到最后会卡住。用 ffprobe 一看报告的时长只有实际的一半左右。我最初的判断是分片没下全于是把每个分片的字节数和清单里的区间长度逐个比对全都对得上。接着怀疑是合并顺序错了重新检查了一遍拼接逻辑也没问题。真正的突破点是拿一个已知正常的文件和出问题的文件做二进制对比。正常的文件开头有一段明显的ftyp和moov结构出问题的文件开头直接就是moof。这说明初始化段没有被写进去。回头看代码问题出在解析清单时EXT-X-MAP那一行是带属性列表的我的正则写得太窄只匹配了不带引号的情况导致init_url一直是None而后面拼接时对None做了静默跳过——因为我在写的时候用了if init_url:这种防御性判断反而把错误掩盖掉了。修完之后我加了一条断言拼接开始前如果init_url为空就直接抛异常绝不静默继续。这条规则后来帮我挡住了好几次类似的隐性失败。6.2 爆音与杂音分片错序的典型症状另一个案例更隐蔽。文件时长完全正确播放也正常但在某些位置会出现很短的咔声。这种问题在整轨试听时很容易被忽略是我用耳机逐段听的时候才发现的。原因是分片的写入顺序和清单顺序不一致。我早期为了提速用了asyncio.gather并发抓分片然后用一个共享的写文件句柄边抓边写。并发返回的顺序是不确定的写进去的字节自然就乱了。因为 fMP4 的分片边界对齐得比较好乱序之后大部分数据仍能解码但衔接处会出现采样不连续听起来就是一声脆响。修法很简单并发抓取可以保留但必须先把所有分片按索引放进一个字典等全部完成后再按顺序写盘。或者更省内存的做法是抓完立即按索引命名存到临时目录最后再统一顺序拼接。我选了后者因为批量任务时内存占用更低。6.3 其他几个高频问题速查除了上面两个大头还有一些零碎但高频的问题整理成一张表方便对照现象根因处理方式单个分片请求一直超时该区间的地址已过期重新解析清单拿新地址不要重试旧地址分片全部成功但拼接失败临时目录磁盘空间不足下载前检查可用空间按曲目总大小预留标签写入报错但文件能放容器实际格式与扩展名不一致用 ffprobe 探测真实容器按结果选写入器封面在某些播放器不显示图片格式标识与实际不符按响应的 Content-Type 决定 imageformat批量跑一半进程静默退出未捕获的异常在任务协程里抛出每个任务包一层 try/except异常记入失败队列那张表里最后一条是我用血换来的。asyncio里如果某个任务协程抛了未捕获异常而你又没有正确地await或者收集它的结果这个异常可能就悄无声息地消失了主流程继续往下跑你只会发现怎么少了几首。所以现在我的任务调度器里每一个任务的执行都包在一层统一的异常处理里失败信息连同原始地址一起写进失败队列最后统一报告。7. 使用边界哪些内容该下哪些不该碰技术上跑通之后还有一个绕不开的问题必须说清楚因为这决定了这套工具是自用归档还是越界使用。7.1 平台侧的下载许可与授权协议SoundCloud 上并不是所有曲目都允许下载。曲目对象里有一个表示下载权限的字段创作者在发布时可以打开或关闭它。打开之后页面上会出现下载按钮这代表创作者明确允许听众把文件拿走。对于这类曲目通过接口拿文件是完全符合平台设计意图的行为。另一类是标注了开放授权协议的曲目。这类作品的权利人已经通过协议明确授予了复制和传播的许可只要遵守协议里的署名等条件下载和再使用都是被允许的。我在做归档的时候会优先识别这两类把它们和普通曲目分开存放并在info.json里记录授权信息。至于那些既没开下载权限、也没标注开放协议的曲目正确的做法是老老实实通过平台的收藏、歌单功能去管理而不是绕开限制把文件拿走。这一点我在代码里做了硬性拦截解析元数据时先检查下载许可标志不满足条件就直接跳过并记录原因不进入下载队列。7.2 个人离线备份的合理尺度即便是允许下载的曲目使用方式也有边界。我给自己划的线是只下载我自己上传的作品以及明确授权下载的他人作品下载后仅用于个人离线收听和本地归档不再分发。这条线看起来保守但它让整个工具的使用场景非常清晰——它是一个个人资料管理工具而不是一个内容获取工具。落到代码层面我在 CLI 入口加了一个显式的确认环节批量任务开始前会把将要下载的曲目列表和它们的授权状态打印出来需要手动确认才会继续。这个设计一开始只是为了调试方便后来发现它其实是个很好的自我约束机制当你看到列表里混进了不该下的东西时会在按下回车之前就停下来。8. 最后一点实操体会这套东西我从最初的一百多行脚本慢慢长到现在带状态机、带并发控制、带元数据管道的完整工具中间重构过三次。如果让我给准备动手的人一句建议那会是先把单首曲目的完整链路——从页面解析到分片合并再到标签写入——彻底跑通并且验证过再去碰批量。因为批量只是把单曲逻辑放进循环真正难的部分全在单曲链路里。我见过太多人一上来就搭异步调度框架、搭状态持久化结果单曲下载本身就有隐性 bug等到批量跑出问题的时候根本分不清是调度层的锅还是下载层的锅排查成本翻好几倍。另外这套链路高度依赖平台当前的接口形态任何一个环节的字段命名、清单结构、鉴权方式发生变化代码都得跟着调整。所以我在实现时刻意把解析和下载拆成了两层中间用一个数据结构衔接。这样接口一变我只需要改解析层下载层和元数据层完全不用动。这个分层在第一年里就救了我不下五次。单曲体积方面也可以给个参考一首五分钟左右的曲目高码率 AAC 流一般在 8 到 12 MB 之间分片数量在 25 到 40 个之间。按这个量级估算磁盘和带宽比凭感觉拍数字靠谱得多。我一开始按MP3 一首 10 MB估结果遇到一批较长的现场录音单曲接近 40 MB硬盘规划直接失准后来改成按曲目时长动态估算才稳定下来。