5 分钟跑通抖音批量下载：douyin-downloader 完整上手指南-平芜编程栈

5 分钟跑通抖音批量下载：douyin-downloader 完整上手指南

【免费下载链接】douyin-downloaderA practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fallback support. 抖音批量下载工具，去水印，支持视频、图集、合集、音乐(原声)。项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader

douyin-downloader 是一个开源免费的抖音批量下载工具：粘贴单条链接或作者主页链接，即可无水印抓取视频、图集、音乐或整页作品，自带进度显示、失败重试和 SQLite 去重，适合把抖音内容存到本地归档的个人用户。

粘贴抖音链接后自动识别作品类型，点击即可开始下载（截图来自桌面版 Douzy，与 CLI 共用同一套后端）

🎯 它到底能做什么

这一节先讲清该工具覆盖哪些下载需求，方便你判断是否匹配自己的场景。

单条与批量下载：粘贴单个视频、图文、音乐、合集或作者主页链接，支持多链接并发下载；典型用途是批量归档某个作者的全部作品。
无水印优先、最高清挑选：自动选择无水印视频源，并按码率挑最高清；用途是留下干净的素材文件方便二次剪辑。
去重与增量：SQLite 数据库加本地文件双重去重，重复运行只拉取新增内容；用途是定期同步关注博主的新作品。
容错与浏览器兜底：默认限速 2 请求/秒，失败按 1s/2s/5s 指数退避重试，翻页受限时自动启动浏览器并支持人工过验证码；用途是数百个作品的深度翻页。

🚀 三步跑起来

这一节给出最小可运行路径，要求 Python 3.8+，macOS、Linux、Windows 均可。

第 1 步：获取代码

git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader

第 2 步：安装依赖

pip install -r requirements.txt

需要浏览器兜底时，再执行pip install playwright和python -m playwright install chromium。

第 3 步：拿 Cookie 并第一次运行

cp config.example.yml config.yml python -m tools.cookie_fetcher --config config.yml python run.py -c config.yml

Cookie 工具会弹出浏览器，登录抖音后回终端按 Enter，程序把 Cookie 写回配置。之后在config.yml里填好要下载的链接，run.py就会按配置开始批量下载。

任务中心实时展示每个任务的进度与成功/失败计数，可一键打开下载目录

📋 场景手册：按需求查

下表列出 4 个高频需求，对号入座即可，参数都对应config.yml里的真实键名。

你的需求	用什么	注意事项
保存单条视频/图文/音乐	`link`填单条链接，或命令行`-u`追加	短链`v.douyin.com`会自动解析
整站收集作者作品	`/user/...`链接 +`mode: [post]`，`number.post: 0`	0 表示不限数量，深翻页可能需浏览器兜底
下载收藏夹/收藏合集	`/user/self?showTab=favorite_collection`+`mode: [collect]`或`[collectmix]`	必须已登录 Cookie，且不能与其他模式混用
只取新发布的作品	`increase: {post: true}`+`database: true`	增量模式依赖数据库记录

以收集作者作品为例，最小配置长这样：

link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post number: post: 0 # 0 表示不限 thread: 5

同一套后端还有桌面版 Douzy（内测中），场景管理更直观：

关注页标记每位博主的新作品，可筛选后直接批量下载

同步当前账号的收藏合集，支持一键下载整个合集

🧩 设计上的讲究

这一节讲三个让长时间任务跑得住的技术细节。

双重去重机制：下载前既查 SQLite 记录，也扫描本地文件名里的 aweme_id，命中任一即跳过；数据库有记录但文件缺失时会触发重新下载。实现见 storage/database.py。
限速、重试与完整性校验：默认 2 请求/秒限速，失败请求指数退避重试，下载完成后按 Content-Length 比对校验，不完整的文件自动清理并重试。这套逻辑集中在 control/。
策略 + 工厂 + 注册表：post/like/mix/music/collect 每种下载模式对应 core/user_modes/ 里的一个策略类，core/ 用工厂按链接类型挑选下载器；新增模式只需注册新策略，不改动现有下载流程。

🧰 进阶玩法

这一节挑两个对进阶用户有价值的功能，点到为止。

热搜榜与关键词搜索：直接拉取抖音热搜榜前 N 名或按关键词搜索作品，结果落盘为 JSONL：

python run.py --hot-board 30 -p ./Downloaded python run.py --search "猫咪" --search-max 100 -p ./Downloaded

REST API 服务模式：pip install fastapi uvicorn后用python run.py --serve --serve-port 8000启动，其他程序可 POST/api/v1/download提交任务、GET 查询任务状态。

⚠️ 踩坑速查

这一节收录 4 个高频问题，问题一句话、解决一句话。

只能抓到 20 个作品：翻页受风控限制，设browser_fallback.enabled: true并保持headless: false，浏览器弹出后手动完成验证。
Cookie 失效、请求失败：重新执行python -m tools.cookie_fetcher --config config.yml，重新登录写回。
进度刷屏看不清日志：把progress.quiet_logs设为true，调试时再加-v。
单视频、合集、点赞、收藏下载失败：抖音 Argus 风控门禁（2026-08/09 起）拦截非浏览器请求，主页作品（post）可走浏览器兜底，其余类型建议改用桌面版 Douzy。