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 是一款主打抖音批量下载的开源工具，去水印、支持视频/图文/合集/音乐/直播，它想解决的只有一件事：把"下载抖音内容"从一小时的手工活，变成一条命令的事。

先别急着收藏：你真正缺的是一次能跑通的批量下载

回想一下你最常干的几件事：看到喜欢的视频想存下来、某个博主更新太快想一次性收全、做课件需要一批同类素材、直播课结束想留档。单独做任何一件都不难，难在重复。今天存 3 条、明天存 5 条，加上命名混乱、重复下载、封面丢失，攒到最后就是一堆没法用的文件。

而批量场景更让人头大：博主主页几百条作品，手动翻页点保存，手酸不说还容易漏；平台对高频请求有风控，脚本一跑就断；好不容易下完了，文件名全是乱码，事后找都找不到。

douyin-downloader 的做法是：把"解析 → 去水印 → 挑最高清 → 建目录 → 存元数据 → 跳过已下载"这一整条链路自动化，剩下的事交给你按回车。下面我们直接从"能不能跑起来"开始验证。

第一次运行：5 分钟把第一支抖音视频拿到手

先别管复杂配置，我们走最短路径。

第 1 步：装依赖（需要 Python 3.8+，Windows / macOS / Linux 都行）

git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader pip install -r requirements.txt

第 2 步：拿 Cookie。访问抖音接口需要登录态，工具自带了自动获取脚本，会打开浏览器让你扫码登录，登录完回到终端按回车，Cookie 会自动写进配置：

python -m tools.cookie_fetcher --config config.yml

第 3 步：写一个最小配置。新建config.yml，把你复制的视频链接粘进去：

link: - https://www.douyin.com/video/7604129988555574538 path: ./Downloaded/ thread: 5 retry_times: 3 database: true

第 4 步：运行

python run.py -c config.yml

看到进度条走完，Downloaded/目录里就会出现一个以"日期_标题_id"命名的文件夹，里面是去水印的视频、封面图、背景音乐和一份 JSON 元数据。到这里，你的第一个任务已经跑通了，全程五分钟以内。

想更省事？命令行可以直接追加链接，临时下载不用改配置：python run.py -c config.yml -u "https://www.douyin.com/video/xxxx" -p ./Downloaded

一张表看懂 douyin-downloader 的能力边界与适用人群

第一次运行成功后，你可能想知道：它到底还能干多少事？下面这张表按"功能能力 + 适用人群"整理，方便你对号入座。

它的"去重"是底层能力，不是开关：SQLite 数据库 + 本地文件名双重判断，同一个作品在多个模式下也不会重复下载，增量场景下只拉新增内容。这一点对批量任务至关重要，后面实操时会看到它怎么帮你省时间。

分步实操：从环境准备到跑通第一个批量下载任务

如果你需要的不只是单条视频，而是"一个博主的所有作品"，请按下面这套完整流程走。

① 复制官方示例配置再改，别从零手写

项目自带一份带注释的完整配置，先复制一份：

cp config.example.yml config.yml

配置示例文件 里每个字段都有说明，建议保留注释逐项看。

② 按需配置"下载什么"

把link换成博主主页地址，用mode和number控制范围：

link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post - like number: post: 100 # 每个模式下载多少条，0 = 全量 like: 50

想同时收合集和音乐，把mix、music也加进mode即可。跨模式自动去重，同一个作品不会下两遍。

③ 决定要不要"增量"

如果你会反复跑同一个博主（比如追更），开增量模式，它只下载数据库里没有的新作品：

increase: post: true database: true # 增量依赖数据库记录，务必开着

④ 启动并观察输出

python run.py -c config.yml -v

-v会显示完整日志，方便第一次跑的时候看清每个环节。下载完成后目录结构长这样：

Downloaded/ └── 作者名/ └── post/ └── 2026-08-01_作品标题_aweme_id/ ├── xxx.mp4 # 无水印视频 ├── xxx_cover.jpg # 封面 ├── xxx_music.mp3 # 原声音乐 └── xxx_data.json # 完整元数据

⑤ 遇到翻页风控？启动浏览器兜底

批量翻页时平台可能弹验证码，工具内置了浏览器兜底策略：API 受限时自动切换到真实浏览器滚动加载，弹窗出来你手动过一下验证即可。相关配置默认是开着的，保持下面这样就好：

browser_fallback: enabled: true headless: false

调参、增量与六个容易踩的坑

常用参数速查

命令行参数不多，但每个都实用：

性能怎么调

• 并发数：thread默认 5，宽带充足可以调到 8；但别盲目拉高，平台有速率限制，默认每秒 2 个请求，调太高反而容易触发风控。
• 重试策略：retry_times: 3对应指数退避（1s、2s、5s），网络不稳定时提到 5 更稳妥。
• 时间过滤：只要某段时间的作品，用start_time/end_time，格式YYYY-MM-DD。
• 静默日志：progress.quiet_logs: true能让进度阶段不刷屏，跑批量任务时观感好很多。

六个容易踩的坑

1. number默认只有 1：示例配置里post: 1是拿来试水的，想全量务必改成0，否则跑完只有一条。
2. 只删数据库不删文件，不会重新下载：程序会扫描本地文件名里的作品 ID 去重；反过来只删文件会触发重下。想彻底重下某个作品，文件和数据都要清。
3. collect/collectmix必须单独用：收藏夹模式不能和post/like/mix/music混在一起跑。
4. 增量模式依赖数据库：increase要生效，database: true必须开着。
5. 直播 HLS 源只保存 playlist：FLV 源可以直接播放；HLS 源需要自己用 ffmpeg 做后处理。
6. 只抓到 20 条是风控信号：别怀疑配置写错了，确认浏览器兜底开着、弹出验证时手动完成，别急着关窗口。

三个真实场景的时间账

场景一：追更博主，每天只花 30 秒

运营同学每天要盯着 8 个对标账号的新作品。以前的做法是上班后逐个翻主页、手动下载，一个人要花掉 20 来分钟。现在把这些主页链接写进配置、开increase.post: true，再配一个 crontab 定时任务：

0 9 * * * cd /path/to/douyin-downloader && python run.py -c config.yml >> download.log 2>&1

每天早上 9 点自动跑完增量，人工时间从每天 20 分钟降到 30 秒（看一眼日志确认没异常），一周省下约 2 小时。

场景二：做课程素材库，300 条案例一个下午变 25 分钟

培训机构要按"学科、年级"建抖音案例库，目标 300 条。手动流程是：搜账号 → 翻作品 → 逐个下载 → 手动改文件名归类，两个助教忙一个下午。改用工具后，把几位老师的user链接写进link，配合start_time按学期过滤、thread: 8并发下载，一次脚本约 25 分钟跑完，人力投入降了八成以上，而且每个作品自带元数据 JSON，后续按字段筛选、归档都不用再手工整理。

场景三：直播课留档，断线也不丢已录内容

直播结束没留底，回放权限过期就再也找不回。工具支持直接录直播间：配置live参数后，max_duration_seconds: 0表示一直录到主播下播，中间 Ctrl+C 或网络波动，已录制的字节也会保留并自动提升为正式文件。实测一场 90 分钟的直播课，录完直接得到 FLV 文件和直播间元数据快照，无需人工守着录屏软件。

高频问题快答：四个拦路问题的标准解法

Q1：只下到 20 条作品，后面全断了？翻页风控，最常见的现象。确认browser_fallback.enabled: true且headless: false，弹窗出现后手动完成验证再让它继续，不要秒关窗口。

Q2：Cookie 失效怎么办？重新跑一遍python -m tools.cookie_fetcher --config config.yml扫码刷新即可。工具本身也能自动检测登录失效，交互环境下会主动拉起浏览器重新登录并自动重试一次。

Q3：想重新下载某个作品，为什么它一直"跳过已存在"？双重去重机制在起作用。想重下，需要同时清理：本地文件（文件名含作品 ID 的目录）和数据库记录（sqlite3 dy_downloader.db "DELETE FROM aweme WHERE aweme_id = 'xxx';"）。

Q4：开了转写却没生成文字稿？依次检查四件事：transcript.enabled是否为true、下载的必须是视频（图文不转写）、OPENAI_API_KEY（或transcript.api_key）是否有效、response_formats是否包含txt或json。

想完整了解参数和场景，项目里的 使用说明 和根目录的config.example.yml是两份最靠谱的参考，遇到问题先查它们。

现在就动手：三步行动清单

技术文章看得再多，不如亲自跑一次。给你一份可直接照做的清单：

1. 装环境：克隆https://gitcode.com/GitHub_Trending/do/douyin-downloader，pip install -r requirements.txt，顺手装好 playwright（浏览器兜底和自动取 Cookie 都要用它）。
2. 拿 Cookie 跑通首单：python -m tools.cookie_fetcher --config config.yml扫码登录，然后粘一条视频链接到config.yml，python run.py -c config.yml确认下载成功。
3. 升级到批量 + 自动化：换成博主主页链接，调好mode/number/increase，跑一次全量；确认无误后再加定时任务和通知推送，让它在后台替你干活。

记住两句话：批量下载的收益不在第一次运行，而在第 100 次；去重和增量是让你敢反复跑的安全网。从今天这支视频开始，把重复的体力活交给工具，把时间留给自己。

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