1. 批量下载这件事为什么值得认真做一套工具做内容运营和素材整理的朋友大概都有过这种体验刷到一个账号的系列作品想整体保存下来做竞品分析或者二次剪辑参考结果只能一条一条手动存几十条视频点下来手指都酸了存完还发现画面上挂着平台水印裁掉水印又破坏了构图。更麻烦的是有些作品是图文合集、有些是带背景音乐的原声、有些是直播回放类型不一样保存方式也不一样手动操作根本没法统一处理。这就是我最初动手折腾批量下载工具的出发点。标题里提到的 douyin-downloader本质上是一套面向短视频平台的批量内容归档方案核心能力可以拆成三块批量解析一次性拿到某个账号或某个合集下的全部作品列表、无水印保存拿到原始媒体文件而不是带水印的播放流、全类型覆盖视频、图文、原声、合集、直播回放都能处理。它解决的不是“能不能下载”这个初级问题而是“能不能高效、干净、成体系地归档”这个进阶需求。这套东西适合谁我梳理了一下大致三类人用得上一是做竞品分析和选题调研的内容从业者需要把对标账号的作品成批存下来反复看二是做二次创作的剪辑爱好者需要干净的无水印素材三是做个人数字资产管理的普通用户想把自己喜欢的创作者作品存到本地长期保存。不管你是完全没写过代码的小白还是有一定脚本基础的半技术流下面的内容我都会尽量把原理讲透、把步骤拆细让你照着做就能跑起来。需要先说明一点批量下载工具的使用边界要自己把握好保存下来的内容仅限个人学习、研究和合理引用不要用于商业传播或二次分发这是所有做内容归档的人都应该守住的基本线。工具本身是中性的怎么用取决于使用者。2. 整体方案设计为什么是“解析下载”两段式架构2.1 核心思路拆解先拿清单再取文件很多人第一次接触这类工具会以为它是“模拟点击播放然后录屏”其实完全不是。真正高效的批量下载走的是接口解析路线整个流程拆成两个独立阶段第一阶段是列表解析。你给它一个账号主页链接或者合集链接它去请求平台返回的作品列表数据拿到每一条作品的唯一标识、标题、类型、发布时间等元信息。这一步只拿“清单”不碰媒体文件速度快、开销小。第二阶段是媒体下载。拿着清单里每一条作品的标识逐条去请求对应的媒体资源地址把视频流或图片集下载到本地。这一步才是真正消耗带宽的环节。为什么要把两段拆开我踩过的坑告诉我合在一起做会非常难受。列表解析如果失败你根本不知道是网络问题还是链接问题下载如果中途断了你也没法单独重试某一条。拆成两段之后清单可以先落盘成 JSON 文件下载阶段读清单执行断了就断点续传某一条失败就单独重跑那一条整个流程的可控性完全不一样。提示清单落盘这个设计是整套方案里最值得抄的作业。哪怕你后面不用现成工具自己写脚本也强烈建议把“解析结果”和“下载动作”解耦这是批量任务稳定性的根基。2.2 无水印的原理拿原始资源而不是播放流水印这件事得说清楚。平台在网页端或 App 端播放时给你的是经过转码、叠加了水印的播放流但作品本身在服务端存的是原始上传文件通常不带水印。批量下载工具之所以能拿到无水印版本是因为它请求的是原始媒体资源地址而不是播放器实际渲染的那条流。这里有个关键细节原始资源地址往往不是直接暴露在页面 HTML 里的而是藏在页面加载时请求的某个数据接口的返回体里。工具要做的就是模拟这个数据请求从返回的 JSON 结构里把媒体地址字段提取出来。不同作品类型视频、图文对应的字段结构不一样所以解析逻辑要按类型分支处理这也是为什么“全类型覆盖”本身就是一个技术难点不是简单加个判断就行。2.3 方案选型为什么用脚本而不是现成软件市面上确实有一些图形化的下载软件但我最终选择脚本方案理由有三个。第一是可控性脚本能精确控制请求头、并发数、重试策略出问题能定位到具体哪一行第二是可扩展今天想加个“只下载最近30天作品”的过滤逻辑改几行代码就行图形软件只能干瞪眼第三是可批量脚本天然适合挂定时任务比如每天凌晨自动同步某个账号的新作品这是图形软件做不到的。脚本方案的语言选择上Python 是首选。原因很实际请求库成熟requests 一把梭、JSON 处理方便、文件操作简单而且社区里同类项目的参考实现多遇到问题好搜。如果你只会 JavaScriptNode.js 也能做但 Python 在数据处理上的顺手程度确实更高一档。3. 核心细节解析请求构造与数据提取的关键点3.1 请求头构造让服务端认你是正常访问批量下载第一个卡点永远是请求被拒。服务端会检查请求头里的多个字段来判断这是不是正常访问最常被检查的是 User-Agent、Referer 和 Cookie 这三样。User-Agent 要伪装成主流浏览器的标识不能是脚本默认的 python-requests 字样否则一眼就被识别。Referer 要带上平台域名表示你是从站内跳转过来的。Cookie 是最关键也最麻烦的一项它承载了你的登录态和会话信息没有有效 Cookie很多接口会直接返回空数据或者要求验证。我的做法是把浏览器里正常访问时抓到的请求头完整复制下来存成一个配置字典脚本里统一带上。这里有个实操心得Cookie 是有有效期的跑批量任务前先手动测一条确认能拿到数据再开跑别等跑了几百条才发现 Cookie 过期了白等半天。HEADERS { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..., Referer: https://平台域名/, Cookie: 从浏览器开发者工具里复制的完整 Cookie 字符串, Accept: application/json, text/plain, */*, }注意Cookie 属于个人敏感凭证配置文件不要提交到公开仓库本地跑完记得清理。这是很多人容易忽略的安全细节。3.2 列表接口的翻页逻辑游标比页码更靠谱拿到作品列表不是一次请求就完事的一个账号可能有几百上千条作品接口一定是分页返回的。这里要区分两种分页模式页码分页page1,2,3...和游标分页cursorxxx。短视频平台的列表接口大多用游标分页返回体里会带一个has_more标志和一个max_cursor或类似的游标值下一次请求把这个游标带上直到has_more为 false 为止。为什么用游标而不是页码因为作品列表是动态变化的用页码翻页在数据变动时会出现重复或遗漏游标则相对稳定。写循环的时候要加两个保护一是最大页数限制防止接口异常导致死循环二是请求间隔每翻一页 sleep 一到两秒别把服务端打得太狠也降低被限流的概率。我一般设 1.5 秒实测下来既不影响效率又比较稳。3.3 媒体地址提取按作品类型分支处理清单拿到手之后每条作品的元信息里会有一个类型字段常见取值包括视频、图文、合集等。不同类型的媒体地址藏在不同的字段路径下解析逻辑必须分支。视频类相对简单元信息里通常有一个播放地址列表取其中码率最高或者标注为原始的那一条即可。图文类要复杂一些它返回的是一个图片地址数组需要遍历数组逐张下载而且图片可能有多种尺寸要挑原图尺寸的那一版。合集类则是一个嵌套结构里面又包含多条子作品需要递归展开。这里有个容易踩的坑有些作品的媒体地址是带时效签名的过期就失效。所以解析和下载之间的间隔不能太长最好是解析完立刻下载或者下载前重新请求一次地址。我早期的版本就是先解析全部再统一下载结果跑到后面一批全部 403排查了半天才发现是签名过期。3.4 文件命名与目录结构归档规范决定后期可用性下载下来的文件如果命名一团糟后期根本没法用。我的命名规范是发布时间_作品标题_作品ID.扩展名发布时间用YYYYMMDD格式这样按文件名排序就是按时间排序。标题里如果有特殊字符斜杠、冒号、问号等要替换掉否则在某些操作系统上会创建文件失败。目录结构按账号名/年份/月份/三层组织这样一年下来几千条作品也能快速定位。图文作品单独建一个子目录里面按01.jpg、02.jpg顺序编号方便还原发布顺序。归档维度具体规则解决的问题文件名时间_标题_ID.扩展名排序即时间线ID 保证唯一目录层级账号/年/月大量文件快速定位图文处理子目录序号命名还原图片发布顺序特殊字符统一替换为下划线避免文件系统报错4. 实操过程从零跑通一套批量下载流程4.1 环境准备与依赖安装先把运行环境搭起来。Python 版本建议 3.8 以上太老的版本有些库装不上。依赖主要就三个requests负责网络请求tqdm负责下载进度条批量下载没有进度条会很难受不知道跑到哪了fake-useragent可选用来随机化 User-Agent。pip install requests tqdm安装完之后建一个项目目录里面放三个文件config.py存请求头和配置参数parser.py负责列表解析downloader.py负责媒体下载。分文件的好处是职责清晰调试的时候知道该看哪个文件。配置参数里我建议把这几项单独拎出来并发下载数建议 3 到 5太高容易被限流、请求超时时间建议 15 秒、重试次数建议 3 次、下载间隔建议 0.5 到 1 秒。这些参数不是拍脑袋定的并发数 3 到 5 是实测下来在稳定性和效率之间的平衡点再高就容易触发风控。4.2 列表解析的完整实现解析阶段的入口是一个账号主页链接或合集链接。第一步是从链接里提取出账号标识或合集标识这个标识是后续请求列表接口的必要参数。提取方式看链接结构通常在路径的某一段里。拿到标识后构造列表请求带上前面说的请求头和分页参数循环请求直到has_more为 false。每一页返回的作品元信息追加到一个总列表里最后把总列表序列化成 JSON 落盘。import json, time, requests from config import HEADERS def fetch_work_list(account_id, max_pages50): all_items, cursor, page [], 0, 0 while page max_pages: params {sec_user_id: account_id, max_cursor: cursor, count: 20} resp requests.get(LIST_API, headersHEADERS, paramsparams, timeout15) data resp.json() items data.get(aweme_list, []) if not items: break all_items.extend(items) if not data.get(has_more): break cursor data.get(max_cursor, 0) page 1 time.sleep(1.5) with open(work_list.json, w, encodingutf-8) as f: json.dump(all_items, f, ensure_asciiFalse, indent2) return all_items这段代码里max_pages50就是前面说的死循环保护time.sleep(1.5)是请求间隔。落盘的 JSON 文件既是下载阶段的输入也是排查问题的依据——如果下载阶段发现某条作品缺字段回头翻 JSON 就能看到解析时到底拿到了什么。4.3 媒体下载与断点续传下载阶段读work_list.json逐条处理。每条作品先判断类型视频走视频下载分支图文走图片批量下载分支。下载前先检查本地是否已存在同名文件存在就跳过这就是最简单的断点续传——不用维护额外的状态文件靠文件系统本身就能判断。视频下载用流式写入避免大文件一次性读进内存def download_video(url, save_path): if os.path.exists(save_path): return skipped for attempt in range(3): try: with requests.get(url, headersHEADERS, streamTrue, timeout30) as r: r.raise_for_status() with open(save_path, wb) as f: for chunk in r.iter_content(chunk_size8192): f.write(chunk) return ok except Exception as e: if attempt 2: return ffailed: {e} time.sleep(2)重试逻辑是必须的网络抖动太常见了。三次重试之间间隔 2 秒给服务端一点喘息时间。下载失败的条目单独记录到一个failed.log里跑完之后针对这个日志再补跑一轮基本能把失败率压到很低。4.4 并发控制与进度反馈单线程下载几百条视频会很慢所以要上并发。但并发不能无脑开我的做法是用concurrent.futures.ThreadPoolExecutor最大工作线程设 4 个配合tqdm显示总进度。from concurrent.futures import ThreadPoolExecutor from tqdm import tqdm with ThreadPoolExecutor(max_workers4) as pool: futures [pool.submit(process_item, item) for item in work_list] for f in tqdm(futures, desc下载进度): f.result()线程数设 4 的理由实测 4 线程时下载速度已经能跑满普通家用带宽再往上加收益递减反而更容易触发限流。如果你的网络环境特殊可以先从 2 线程试起稳定了再往上调。实操心得并发下载时每个线程的请求间隔要错开不要所有线程同一时刻发请求。可以在每个线程的任务开头加一个time.sleep(random.uniform(0, 1))把请求打散稳定性会明显提升。5. 常见问题与排查技巧实录5.1 请求返回空数据或验证页这是最高频的问题表现是接口返回 200 但内容是空的或者返回一段要求验证的 HTML。原因基本锁定在请求头不完整或 Cookie 失效。排查顺序先检查 Cookie 是否过期浏览器里重新登录一次再复制再检查 User-Agent 和 Referer 是否带全最后看请求频率是不是太高被临时限制了。如果是频率问题把并发降到 2、间隔加到 2 秒等十几分钟再试。我遇到过连续跑了两千多条之后开始返回空数据的情况停半小时再跑就恢复了说明是触发了频率限制而不是封禁。5.2 下载到一半中断或文件损坏文件损坏的典型表现是视频能下载但播放器打不开或者图片只显示一半。原因通常是下载过程中连接中断但代码没捕获到写入了不完整的数据。解决办法是下载完成后校验文件大小和响应头里的Content-Length对比不一致就删掉重下。还有一种情况是磁盘空间不足写到一半报错。批量下载前先估算一下总大小单条视频按平均 10MB 算一千条就是 10GB图文按每张 500KB、每条 9 张算一千条图文大概 4.5GB。心里有个数提前清理磁盘。5.3 图文作品的图片顺序错乱图文作品下载下来如果顺序乱了后期根本没法用。问题出在并发下载图片时没有保证顺序。解决办法是图片下载不走并发或者并发但按索引命名后统一重命名。我现在的做法是图片串行下载反正单条图文的图片数量有限串行的速度损失可以接受换来的是顺序绝对可靠。5.4 常见问题速查表现象最可能原因处理方式接口返回空数据Cookie 失效或请求头不全重新复制 Cookie补全请求头返回验证页面请求频率过高降并发、加间隔等待后重试视频无法播放文件下载不完整校验大小删除重下图片顺序错乱并发下载未保序改为串行或按索引重命名媒体地址 403签名过期解析后立即下载或重新请求地址文件名创建失败标题含特殊字符统一替换为下划线5.5 几个容易被忽略的细节第一个细节是时间戳时区。作品发布时间返回的通常是 Unix 时间戳转换成本地时间时要确认时区否则归档目录的月份可能错位。第二个细节是重复作品去重。同一个作品可能因为转发出现在多个列表里下载前用作品 ID 做一次去重能省不少空间。第三个细节是日志留存。每次跑批量任务都留一份运行日志记录开始时间、处理条数、成功失败数出问题的时候这份日志就是最好的排查线索。6. 工具选型与扩展思路6.1 现成工具与自建脚本的取舍如果你只是想偶尔存几条作品现成的图形化工具足够用拖进去点几下就完事。但如果你要做的是成体系的归档——比如持续跟踪几十个账号、每天增量同步、按规则自动分类——那自建脚本的优势就体现出来了。现成工具的通病是参数不可调、失败不可控、扩展不可做而脚本方案在这三点上都是开放的。我的建议是先用现成工具跑通一次完整流程理解“解析-下载”这个基本模型然后再迁移到脚本方案。直接上脚本对纯小白来说门槛偏高容易在环境配置阶段就放弃。6.2 增量同步的扩展做法基础版跑通之后最值得加的扩展是增量同步。做法很简单每次解析完列表后和本地已有的作品 ID 集合做差集只下载新增的部分。本地 ID 集合可以维护在一个文本文件里每下载成功一条就追加一行。这样每天定时跑一次只处理新作品几分钟就能完成同步。再进一步可以加过滤规则比如只下载点赞数超过某个阈值的作品或者只下载指定时间段内的作品。这些规则在解析阶段就能过滤减少无效下载。6.3 长期维护的注意事项平台的数据接口不是一成不变的字段结构、参数名、请求头校验规则都可能调整。所以这套脚本需要定期检查发现解析失败时第一时间对比接口返回结构有没有变化。我的习惯是每个月手动跑一次全量解析看看返回的字段和上次有没有差异提前发现问题比事后排查省事得多。另外归档目录要定期做一次完整性检查随机抽几条文件打开看看能不能正常播放或显示避免长期积累下来一堆损坏文件自己还不知道。这个习惯看起来笨但确实能救命。我在实际使用中最大的体会是批量下载这件事的难点从来不在“下载”本身而在“稳定”和“可维护”。一套能跑一次的脚本和一套能跑一年的脚本差距全在异常处理、断点续传、日志留存这些不起眼的地方。把这几块做扎实了剩下的就是按需扩展的事了。 
长河君 · 2026/10/28 11:03:24 · 阅读 1.2k 批量下载工具设计：解析与下载两段式架构及无水印保存实践
1. 批量下载这件事为什么值得认真做一套工具做内容运营和素材整理的朋友大概都有过这种体验刷到一个账号的系列作品想整体保存下来做竞品分析或者二次剪辑参考结果只能一条一条手动存几十条视频点下来手指都酸了存完还发现画面上挂着平台水印裁掉水印又破坏了构图。更麻烦的是有些作品是图文合集、有些是带背景音乐的原声、有些是直播回放类型不一样保存方式也不一样手动操作根本没法统一处理。这就是我最初动手折腾批量下载工具的出发点。标题里提到的 douyin-downloader本质上是一套面向短视频平台的批量内容归档方案核心能力可以拆成三块批量解析一次性拿到某个账号或某个合集下的全部作品列表、无水印保存拿到原始媒体文件而不是带水印的播放流、全类型覆盖视频、图文、原声、合集、直播回放都能处理。它解决的不是“能不能下载”这个初级问题而是“能不能高效、干净、成体系地归档”这个进阶需求。这套东西适合谁我梳理了一下大致三类人用得上一是做竞品分析和选题调研的内容从业者需要把对标账号的作品成批存下来反复看二是做二次创作的剪辑爱好者需要干净的无水印素材三是做个人数字资产管理的普通用户想把自己喜欢的创作者作品存到本地长期保存。不管你是完全没写过代码的小白还是有一定脚本基础的半技术流下面的内容我都会尽量把原理讲透、把步骤拆细让你照着做就能跑起来。需要先说明一点批量下载工具的使用边界要自己把握好保存下来的内容仅限个人学习、研究和合理引用不要用于商业传播或二次分发这是所有做内容归档的人都应该守住的基本线。工具本身是中性的怎么用取决于使用者。2. 整体方案设计为什么是“解析下载”两段式架构2.1 核心思路拆解先拿清单再取文件很多人第一次接触这类工具会以为它是“模拟点击播放然后录屏”其实完全不是。真正高效的批量下载走的是接口解析路线整个流程拆成两个独立阶段第一阶段是列表解析。你给它一个账号主页链接或者合集链接它去请求平台返回的作品列表数据拿到每一条作品的唯一标识、标题、类型、发布时间等元信息。这一步只拿“清单”不碰媒体文件速度快、开销小。第二阶段是媒体下载。拿着清单里每一条作品的标识逐条去请求对应的媒体资源地址把视频流或图片集下载到本地。这一步才是真正消耗带宽的环节。为什么要把两段拆开我踩过的坑告诉我合在一起做会非常难受。列表解析如果失败你根本不知道是网络问题还是链接问题下载如果中途断了你也没法单独重试某一条。拆成两段之后清单可以先落盘成 JSON 文件下载阶段读清单执行断了就断点续传某一条失败就单独重跑那一条整个流程的可控性完全不一样。提示清单落盘这个设计是整套方案里最值得抄的作业。哪怕你后面不用现成工具自己写脚本也强烈建议把“解析结果”和“下载动作”解耦这是批量任务稳定性的根基。2.2 无水印的原理拿原始资源而不是播放流水印这件事得说清楚。平台在网页端或 App 端播放时给你的是经过转码、叠加了水印的播放流但作品本身在服务端存的是原始上传文件通常不带水印。批量下载工具之所以能拿到无水印版本是因为它请求的是原始媒体资源地址而不是播放器实际渲染的那条流。这里有个关键细节原始资源地址往往不是直接暴露在页面 HTML 里的而是藏在页面加载时请求的某个数据接口的返回体里。工具要做的就是模拟这个数据请求从返回的 JSON 结构里把媒体地址字段提取出来。不同作品类型视频、图文对应的字段结构不一样所以解析逻辑要按类型分支处理这也是为什么“全类型覆盖”本身就是一个技术难点不是简单加个判断就行。2.3 方案选型为什么用脚本而不是现成软件市面上确实有一些图形化的下载软件但我最终选择脚本方案理由有三个。第一是可控性脚本能精确控制请求头、并发数、重试策略出问题能定位到具体哪一行第二是可扩展今天想加个“只下载最近30天作品”的过滤逻辑改几行代码就行图形软件只能干瞪眼第三是可批量脚本天然适合挂定时任务比如每天凌晨自动同步某个账号的新作品这是图形软件做不到的。脚本方案的语言选择上Python 是首选。原因很实际请求库成熟requests 一把梭、JSON 处理方便、文件操作简单而且社区里同类项目的参考实现多遇到问题好搜。如果你只会 JavaScriptNode.js 也能做但 Python 在数据处理上的顺手程度确实更高一档。3. 核心细节解析请求构造与数据提取的关键点3.1 请求头构造让服务端认你是正常访问批量下载第一个卡点永远是请求被拒。服务端会检查请求头里的多个字段来判断这是不是正常访问最常被检查的是 User-Agent、Referer 和 Cookie 这三样。User-Agent 要伪装成主流浏览器的标识不能是脚本默认的 python-requests 字样否则一眼就被识别。Referer 要带上平台域名表示你是从站内跳转过来的。Cookie 是最关键也最麻烦的一项它承载了你的登录态和会话信息没有有效 Cookie很多接口会直接返回空数据或者要求验证。我的做法是把浏览器里正常访问时抓到的请求头完整复制下来存成一个配置字典脚本里统一带上。这里有个实操心得Cookie 是有有效期的跑批量任务前先手动测一条确认能拿到数据再开跑别等跑了几百条才发现 Cookie 过期了白等半天。HEADERS { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..., Referer: https://平台域名/, Cookie: 从浏览器开发者工具里复制的完整 Cookie 字符串, Accept: application/json, text/plain, */*, }注意Cookie 属于个人敏感凭证配置文件不要提交到公开仓库本地跑完记得清理。这是很多人容易忽略的安全细节。3.2 列表接口的翻页逻辑游标比页码更靠谱拿到作品列表不是一次请求就完事的一个账号可能有几百上千条作品接口一定是分页返回的。这里要区分两种分页模式页码分页page1,2,3...和游标分页cursorxxx。短视频平台的列表接口大多用游标分页返回体里会带一个has_more标志和一个max_cursor或类似的游标值下一次请求把这个游标带上直到has_more为 false 为止。为什么用游标而不是页码因为作品列表是动态变化的用页码翻页在数据变动时会出现重复或遗漏游标则相对稳定。写循环的时候要加两个保护一是最大页数限制防止接口异常导致死循环二是请求间隔每翻一页 sleep 一到两秒别把服务端打得太狠也降低被限流的概率。我一般设 1.5 秒实测下来既不影响效率又比较稳。3.3 媒体地址提取按作品类型分支处理清单拿到手之后每条作品的元信息里会有一个类型字段常见取值包括视频、图文、合集等。不同类型的媒体地址藏在不同的字段路径下解析逻辑必须分支。视频类相对简单元信息里通常有一个播放地址列表取其中码率最高或者标注为原始的那一条即可。图文类要复杂一些它返回的是一个图片地址数组需要遍历数组逐张下载而且图片可能有多种尺寸要挑原图尺寸的那一版。合集类则是一个嵌套结构里面又包含多条子作品需要递归展开。这里有个容易踩的坑有些作品的媒体地址是带时效签名的过期就失效。所以解析和下载之间的间隔不能太长最好是解析完立刻下载或者下载前重新请求一次地址。我早期的版本就是先解析全部再统一下载结果跑到后面一批全部 403排查了半天才发现是签名过期。3.4 文件命名与目录结构归档规范决定后期可用性下载下来的文件如果命名一团糟后期根本没法用。我的命名规范是发布时间_作品标题_作品ID.扩展名发布时间用YYYYMMDD格式这样按文件名排序就是按时间排序。标题里如果有特殊字符斜杠、冒号、问号等要替换掉否则在某些操作系统上会创建文件失败。目录结构按账号名/年份/月份/三层组织这样一年下来几千条作品也能快速定位。图文作品单独建一个子目录里面按01.jpg、02.jpg顺序编号方便还原发布顺序。归档维度具体规则解决的问题文件名时间_标题_ID.扩展名排序即时间线ID 保证唯一目录层级账号/年/月大量文件快速定位图文处理子目录序号命名还原图片发布顺序特殊字符统一替换为下划线避免文件系统报错4. 实操过程从零跑通一套批量下载流程4.1 环境准备与依赖安装先把运行环境搭起来。Python 版本建议 3.8 以上太老的版本有些库装不上。依赖主要就三个requests负责网络请求tqdm负责下载进度条批量下载没有进度条会很难受不知道跑到哪了fake-useragent可选用来随机化 User-Agent。pip install requests tqdm安装完之后建一个项目目录里面放三个文件config.py存请求头和配置参数parser.py负责列表解析downloader.py负责媒体下载。分文件的好处是职责清晰调试的时候知道该看哪个文件。配置参数里我建议把这几项单独拎出来并发下载数建议 3 到 5太高容易被限流、请求超时时间建议 15 秒、重试次数建议 3 次、下载间隔建议 0.5 到 1 秒。这些参数不是拍脑袋定的并发数 3 到 5 是实测下来在稳定性和效率之间的平衡点再高就容易触发风控。4.2 列表解析的完整实现解析阶段的入口是一个账号主页链接或合集链接。第一步是从链接里提取出账号标识或合集标识这个标识是后续请求列表接口的必要参数。提取方式看链接结构通常在路径的某一段里。拿到标识后构造列表请求带上前面说的请求头和分页参数循环请求直到has_more为 false。每一页返回的作品元信息追加到一个总列表里最后把总列表序列化成 JSON 落盘。import json, time, requests from config import HEADERS def fetch_work_list(account_id, max_pages50): all_items, cursor, page [], 0, 0 while page max_pages: params {sec_user_id: account_id, max_cursor: cursor, count: 20} resp requests.get(LIST_API, headersHEADERS, paramsparams, timeout15) data resp.json() items data.get(aweme_list, []) if not items: break all_items.extend(items) if not data.get(has_more): break cursor data.get(max_cursor, 0) page 1 time.sleep(1.5) with open(work_list.json, w, encodingutf-8) as f: json.dump(all_items, f, ensure_asciiFalse, indent2) return all_items这段代码里max_pages50就是前面说的死循环保护time.sleep(1.5)是请求间隔。落盘的 JSON 文件既是下载阶段的输入也是排查问题的依据——如果下载阶段发现某条作品缺字段回头翻 JSON 就能看到解析时到底拿到了什么。4.3 媒体下载与断点续传下载阶段读work_list.json逐条处理。每条作品先判断类型视频走视频下载分支图文走图片批量下载分支。下载前先检查本地是否已存在同名文件存在就跳过这就是最简单的断点续传——不用维护额外的状态文件靠文件系统本身就能判断。视频下载用流式写入避免大文件一次性读进内存def download_video(url, save_path): if os.path.exists(save_path): return skipped for attempt in range(3): try: with requests.get(url, headersHEADERS, streamTrue, timeout30) as r: r.raise_for_status() with open(save_path, wb) as f: for chunk in r.iter_content(chunk_size8192): f.write(chunk) return ok except Exception as e: if attempt 2: return ffailed: {e} time.sleep(2)重试逻辑是必须的网络抖动太常见了。三次重试之间间隔 2 秒给服务端一点喘息时间。下载失败的条目单独记录到一个failed.log里跑完之后针对这个日志再补跑一轮基本能把失败率压到很低。4.4 并发控制与进度反馈单线程下载几百条视频会很慢所以要上并发。但并发不能无脑开我的做法是用concurrent.futures.ThreadPoolExecutor最大工作线程设 4 个配合tqdm显示总进度。from concurrent.futures import ThreadPoolExecutor from tqdm import tqdm with ThreadPoolExecutor(max_workers4) as pool: futures [pool.submit(process_item, item) for item in work_list] for f in tqdm(futures, desc下载进度): f.result()线程数设 4 的理由实测 4 线程时下载速度已经能跑满普通家用带宽再往上加收益递减反而更容易触发限流。如果你的网络环境特殊可以先从 2 线程试起稳定了再往上调。实操心得并发下载时每个线程的请求间隔要错开不要所有线程同一时刻发请求。可以在每个线程的任务开头加一个time.sleep(random.uniform(0, 1))把请求打散稳定性会明显提升。5. 常见问题与排查技巧实录5.1 请求返回空数据或验证页这是最高频的问题表现是接口返回 200 但内容是空的或者返回一段要求验证的 HTML。原因基本锁定在请求头不完整或 Cookie 失效。排查顺序先检查 Cookie 是否过期浏览器里重新登录一次再复制再检查 User-Agent 和 Referer 是否带全最后看请求频率是不是太高被临时限制了。如果是频率问题把并发降到 2、间隔加到 2 秒等十几分钟再试。我遇到过连续跑了两千多条之后开始返回空数据的情况停半小时再跑就恢复了说明是触发了频率限制而不是封禁。5.2 下载到一半中断或文件损坏文件损坏的典型表现是视频能下载但播放器打不开或者图片只显示一半。原因通常是下载过程中连接中断但代码没捕获到写入了不完整的数据。解决办法是下载完成后校验文件大小和响应头里的Content-Length对比不一致就删掉重下。还有一种情况是磁盘空间不足写到一半报错。批量下载前先估算一下总大小单条视频按平均 10MB 算一千条就是 10GB图文按每张 500KB、每条 9 张算一千条图文大概 4.5GB。心里有个数提前清理磁盘。5.3 图文作品的图片顺序错乱图文作品下载下来如果顺序乱了后期根本没法用。问题出在并发下载图片时没有保证顺序。解决办法是图片下载不走并发或者并发但按索引命名后统一重命名。我现在的做法是图片串行下载反正单条图文的图片数量有限串行的速度损失可以接受换来的是顺序绝对可靠。5.4 常见问题速查表现象最可能原因处理方式接口返回空数据Cookie 失效或请求头不全重新复制 Cookie补全请求头返回验证页面请求频率过高降并发、加间隔等待后重试视频无法播放文件下载不完整校验大小删除重下图片顺序错乱并发下载未保序改为串行或按索引重命名媒体地址 403签名过期解析后立即下载或重新请求地址文件名创建失败标题含特殊字符统一替换为下划线5.5 几个容易被忽略的细节第一个细节是时间戳时区。作品发布时间返回的通常是 Unix 时间戳转换成本地时间时要确认时区否则归档目录的月份可能错位。第二个细节是重复作品去重。同一个作品可能因为转发出现在多个列表里下载前用作品 ID 做一次去重能省不少空间。第三个细节是日志留存。每次跑批量任务都留一份运行日志记录开始时间、处理条数、成功失败数出问题的时候这份日志就是最好的排查线索。6. 工具选型与扩展思路6.1 现成工具与自建脚本的取舍如果你只是想偶尔存几条作品现成的图形化工具足够用拖进去点几下就完事。但如果你要做的是成体系的归档——比如持续跟踪几十个账号、每天增量同步、按规则自动分类——那自建脚本的优势就体现出来了。现成工具的通病是参数不可调、失败不可控、扩展不可做而脚本方案在这三点上都是开放的。我的建议是先用现成工具跑通一次完整流程理解“解析-下载”这个基本模型然后再迁移到脚本方案。直接上脚本对纯小白来说门槛偏高容易在环境配置阶段就放弃。6.2 增量同步的扩展做法基础版跑通之后最值得加的扩展是增量同步。做法很简单每次解析完列表后和本地已有的作品 ID 集合做差集只下载新增的部分。本地 ID 集合可以维护在一个文本文件里每下载成功一条就追加一行。这样每天定时跑一次只处理新作品几分钟就能完成同步。再进一步可以加过滤规则比如只下载点赞数超过某个阈值的作品或者只下载指定时间段内的作品。这些规则在解析阶段就能过滤减少无效下载。6.3 长期维护的注意事项平台的数据接口不是一成不变的字段结构、参数名、请求头校验规则都可能调整。所以这套脚本需要定期检查发现解析失败时第一时间对比接口返回结构有没有变化。我的习惯是每个月手动跑一次全量解析看看返回的字段和上次有没有差异提前发现问题比事后排查省事得多。另外归档目录要定期做一次完整性检查随机抽几条文件打开看看能不能正常播放或显示避免长期积累下来一堆损坏文件自己还不知道。这个习惯看起来笨但确实能救命。我在实际使用中最大的体会是批量下载这件事的难点从来不在“下载”本身而在“稳定”和“可维护”。一套能跑一次的脚本和一套能跑一年的脚本差距全在异常处理、断点续传、日志留存这些不起眼的地方。把这几块做扎实了剩下的就是按需扩展的事了。