douyin-downloader：抖音批量下载完整指南，一条链接如何快速下完整个主页

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 是一个命令行抖音批量下载工具，最能解决的是把整个博主主页一次性搬空：手动逐条另存 200 条作品要 30 分钟以上，它用默认 5 线程并发、2 请求/秒的限速跑完大约 10 分钟，全程无需盯屏，重复作品自动跳过。

它能干什么

先看输入输出的对应关系：

工程上的差异点集中在几个可核对的机制上：并发默认 5 线程，失败按 1s→2s→5s 指数退避重试（retry_times默认 3，见 control/retry_handler.py）；去重是"扫描本地文件名中的aweme_id+ SQLite 历史记录"双重判断，删文件即会触发重下；每次落盘后按 Content-Length 比对实际字节数，不完整文件自动清理并在下次运行补下；单条作品还有 15 分钟兜底总时限，防止一条坏任务拖死整个队列。当 API 翻页被风控截断时，它会拉起真实浏览器兜底采集，支持人工过验证码（目前仅post模式完整验证过）。

这套后端同时驱动闭测中的桌面版 Douzy，下图是它的链接工作台与任务中心：

首次运行最短路径

项目只有一个命令行入口run.py，行为全部由 YAML 配置驱动，命令行参数（-u追加链接、-t线程数、-p输出目录）只是对配置的临时覆盖，不存在多版本选择问题。

# 克隆仓库并进入目录 git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader

# 安装依赖 pip install -r requirements.txt

# 复制示例配置为正式配置 cp config.example.yml config.yml

# 安装浏览器兜底与自动取 Cookie 所需的 Playwright pip install playwright python -m playwright install chromium

# 自动获取抖音 Cookie，会弹出浏览器，登录抖音后回终端按回车 python -m tools.cookie_fetcher --config config.yml

# 用配置跑一次下载 python run.py -c config.yml

配置模板里每一项都有注释，config.example.yml 可以直接照抄着改。改完后把link填成目标链接、number.post改为要下载的数量（0 表示全部）即可。

两个真实任务演练

任务一：批量下载某个博主的全部作品

目的：把目标博主发布的所有作品无水印搬进本地，并保留可检索的元数据。

# config.yml：主页批量下载 + 元数据开关 link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post number: post: 0 # 0 = 不限量，全部下载 json: true # 每条作品附带完整元数据 JSON

python run.py -c config.yml

结果：终端实时显示进度条与每条任务的状态（成功 / 跳过 / 失败）。磁盘上生成Downloaded/作者名/post/2024-02-07_标题_aweme_id/结构，目录内是.mp4视频与_data.json元数据（发布时间、点赞数、评论数、描述）；下载根目录多一个download_manifest.jsonl总清单，SQLite 库dy_downloader.db记录下载历史，用于下次增量判断。

任务二：按时间窗口备份点赞作品，之后增量同步

目的：只备份某段时间内的点赞内容，之后重复运行只补新增部分。

# config.yml：点赞模式 + 时间窗 + 增量开关 link: - https://www.douyin.com/user/MS4wLjABAAAAyyyy mode: - like number: like: 0 start_time: "2025-01-01" end_time: "" # 留空表示不限结束时间 increase: like: true # 磁盘上已存在的主文件直接跳过

python run.py -c config.yml

结果：🔁 时间窗外的作品在拉取阶段就被过滤，不会占用下载并发；已落盘的作品在下次运行时按"文件存在且非空"直接跳过，所以把它挂成定时任务后，日常同步通常只花几秒钟。注意like需要有效的登录 Cookie，且collect/collectmix（收藏夹模式）目前只支持单独使用，不能与post/like/mix/music混写在同一个mode里。

避坑清单

1. 只下到 20 条左右就停了→ API 翻页触发风控，属于常见限流行为 → 确认browser_fallback.enabled: true且headless: false，在弹出的浏览器里人工完成验证、不要提前关窗口。
2. 下载提示"需要登录"或链接解析失败→ Cookie 过期，抖音会定期更新安全策略 → 重新执行python -m tools.cookie_fetcher --config config.yml刷新即可。
3. 把thread调到很高后反而大量失败→ 并发过高触发接口限流，且请求侧限速默认只有 2 请求/秒 → 保持thread: 5到 8，先确认带宽充足。
4. 删了dy_downloader.db却不会重新下载→ 去重是"数据库记录 + 本地文件"双检，本地文件存在时直接跳过 → 只删本地文件（目录名含aweme_id）即可触发重下；两者都删才是完全重置。
5. 视频下载成功但没有transcript.txt→ 转写默认关闭，且图集类作品不参与转写 → 打开transcript.enabled: true并设置OPENAI_API_KEY，只下载视频类作品。

更深入的模块划分（API 客户端、下载策略、存储层）见 PROJECT_SUMMARY.md。

把任务一的配置写进config.yml，运行python run.py -c config.yml，让它先跑完一个小数量试试，再放开number上限。

【免费下载链接】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