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 是一个命令行抖音批量下载工具：一条链接加一份 YAML 配置，无水印视频、图文、合集、音乐与直播录制自动归档到本地，内置重试、SQLite 去重与浏览器兜底，适合长期存档抖音内容。

装好环境，拿到登录态

这一节把拉代码、装依赖、扫码登录一次做完，大约五分钟，后面所有命令都建立在它之上。只需 Python 3.8+，macOS、Linux、Windows 均可。

1. 拉代码并安装依赖，终端无红色报错即环境就绪：

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

2. 安装浏览器组件。浏览器兜底和自动获取 Cookie 都依赖 Playwright：

pip install playwright python -m playwright install chromium

3. 拷贝配置模板并扫码登录，模板里每个字段都有中文注释，可先通读 config.example.yml：

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

浏览器会弹出登录页，扫码后回到终端按 Enter，Cookie 自动写入配置，不用手动复制。弹窗后卡住的话，先确认上一步 chromium 是否装好。自动抓取脚本的源码在 tools/cookie_fetcher.py。

验证点：打开config.yml，cookies下msToken、ttwid等字段不再是YOUR_...占位符。这一步别省：抖音大量内容只对登录用户开放，Cookie 没配对，后面的请求基本都会失败。

跑通第一条无水印视频

这一节是全文的验证主线：跑通它，说明环境、登录态、网络都没问题。

配置里真正必填的只有三项：link、path、cookies。把link改成一条视频链接：

link: - https://www.douyin.com/video/760412345678901234567

然后启动：

python run.py -c config.yml

验证点：终端末尾出现完成统计；Downloaded/下生成以作者名命名的目录，里面是可直接播放的无水印 mp4。默认每条作品放在{date}_{title}_{id}命名的文件夹里，打开cover、music、json后会在旁边多出生成的封面、原声、元数据文件。

命令行参数可以临时覆盖配置，不用改文件：

python run.py -c config.yml -u "https://www.douyin.com/video/760412345678901234567" -t 8

-u追加链接、-t调并发、-p换输出目录。图文笔记同理，链接换成/note/{note_id}即可，图片按顺序归档。

⚠️ 注意：2026 年年中起，抖音风控已拦截 CLI 的多数直连接口——点赞/收藏类 2026-08 起失效，单个视频/图文、合集、音乐 2026-09 起失效，主页作品直连翻页同样被拒，只剩浏览器兜底一条路。运行时若遇到 403，先看文末"排障"一节；这类下载也可以改用桌面版 Douzy（内置登录窗口代发请求，目前内测中）。

备份一位博主的主页

存某位博主的全部作品，用批量模式而不是逐条粘贴。填主页链接，在mode勾选要抓的类型，number给每种类型设上限（0表示不限）：

link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post - mix number: post: 50 # 只抓 50 条作品 mix: 20

运行方式不变，仍是python run.py -c config.yml。

验证点：跑完后内容按Downloaded/{作者}/post/、Downloaded/{作者}/mix/分层归档，Downloaded/download_manifest.jsonl里能逐条对上作品清单。post作品、like喜欢、mix合集、music音乐可以混在同一次任务里，跨模式自动去重，同一条作品不会下两遍。

易错点：收藏夹和收藏合集（collect/collectmix）只能单独使用，不能和上面四种模式混写，且只认当前登录 Cookie 对应的账号。桌面版 Douzy 提供类似的"关注同步 + 筛选新作品"能力，效果可以参考：

录下一场完整直播

这一节解决整场直播录制，不用开录屏软件。把直播间链接直接填进link：

link: - https://live.douyin.com/123456789 live: max_duration_seconds: 3600 # 0 = 录到主播下播

验证点：FLV 文件和房间元数据 JSON 保存在Downloaded/{作者}/live/下，FLV 可直接播放。主播下播、录满时长或你手动 Ctrl+C，已录下的字节都会保留。

边界要心里有数：直播录制接口官方标注为 experimental，未覆盖所有直播场景，重要场次建议同时人工备份一份；若拉的是 HLS 源，只会保存 playlist 文件，需要 ffmpeg 后处理。

只导出数据不下载：热搜与关键词

只想收集数据、不落地文件时，两条命令就够，这两个接口目前不受风控影响（2026-09 实测仍可直接连接）：

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

验证点：分别在Downloaded/hot_board/和Downloaded/search/下生成带时间戳的 JSONL 文件（搜索的文件名还含关键词），可直接用 pandas 或 jq 做二次筛选。

易错点：--search默认只拉 50 条，要更多就显式给--search-max。想顺手留评论，把comments.enabled设为true，每条作品的媒体文件旁会生成{date}_{title}_{id}_comments.json，include_replies: true可多拉二级回复。

进阶调优：去重、增量与通知

批量任务跑几十分钟，最怕中途崩掉白跑或硬盘堆出重复文件。这一节只讲值得动的配置。

几组搭配值得记牢：

• 去重双保险：判断逻辑是"数据库记录 + 本地文件"双重检查。只删库不清文件不会触发重下，两者都清才会重新下载；只删文件不删库则会重下。
• 重试兜底：retry_times: 3配合内置 2 请求/秒的限速，网络抖动不会留下缺口；下载还有 Content-Length 完整性校验，残文件自动清理并重试。
• 并发循序渐进：thread从 5 起步，稳定了再提到 8。一上来拉满容易触发风控，反而比慢一点更慢。

想重新下载某条被跳过的作品，把本地文件夹和库中记录一起清掉：

rm -rf "Downloaded/作者名/post/*_760412345678901234567" sqlite3 dy_downloader.db "DELETE FROM aweme WHERE aweme_id = '760412345678901234567';"

按作者清全部、清空整库的完整命令见 README.zh-CN.md 的"重新下载"一节。

遇到问题时来这里找答案

跑起来之后，遇到的麻烦基本是下面这几类，对着现象查。

• 主页只抓到 20 条左右？翻页触发了风控。确认browser_fallback.enabled: true且headless: false，浏览器弹窗出现后手动过验证码、别立刻关窗；或用start_time/end_time分段抓。
• 突然大面积失败？Cookie 过期了。重跑python -m tools.cookie_fetcher --config config.yml更新登录态。
• 大量请求 403，报错提到 Argus？抖音风控已拦截 CLI 直连单个视频/图文、合集、音乐、点赞/收藏类接口（2026-08 起分批生效）。主页作品可试浏览器兜底，其余下载建议改用桌面版 Douzy：

• 硬盘里堆出重复文件？去重没开。database: true配合increase走增量。
• 想重下某一条？见上一节的重新下载命令，文件和库一起清。
• 进度输出很吵？progress.quiet_logs: true可在进度阶段静默；排查时临时加-v或--show-warnings。
• 速度慢？thread提到 8、retry_times给 3，逐步上调，别一次跳满。

上手建议

长期用之前，先养成几个习惯：

1. 先用一条单视频链接验证 Cookie 和网络，再上主页批量。
2. 测试阶段把number.post设成 1~5，跑通后再放开到 0。
3. 不同任务分配置（如config_test.yml、config_daily.yml），别共用一份。
4. Cookie 失效是常态，把它当周期性维护项，不是故障。
5. 长任务加notifications推送，跑完手机上就能收到。

本项目仅供技术学习与个人数据管理使用，请在合法合规的前提下使用，尊重内容版权与创作者权益。

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