抖音批量下载工具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是一款开源的抖音批量下载工具，支持视频、图文、合集、音乐、收藏夹等多种内容一键抓取，自动去水印、智能去重、保存完整元数据，并提供浏览器兜底与直播录制能力。无论你是内容创作者、做研究的同学，还是想备份个人收藏的普通用户，这篇文章都会带你从零开始，把它的全部价值用起来。

先看一组对比：手动搬运和工具抓取差距有多大

如果你需要为项目收集 500 条指定话题的抖音视频，手动操作是这样的：复制链接、等待页面加载、右键另存、重命名，再粘贴下一条……一个熟练的人连续操作，也至少要消耗大半天，而且中途很容易出现漏存、重复下载和文件命名混乱。

使用 douyin-downloader 之后，同样的任务可以在几分钟内完成。核心原因在于它把整套流程拆成了可并行的流水线：

多线程并发抓取（默认 5 线程，可调高到 8~10）
失败自动重试，采用 1 秒、2 秒、5 秒的指数退避策略
内置频率控制（默认每秒 2 个请求），避免触发平台风控
SQLite 数据库加本地文件双重去重，同一作品永远不会存两遍

一句话总结：它把"能不能下载"的问题变成了"想下载多少"的问题，你只需要关心数量和范围，剩下的交给工具。

环境搭建：三步让工具跑起来

工具基于 Python 3.8+ 开发，macOS、Linux、Windows 都可以运行。开始前先获取项目代码：

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

第一步：安装依赖

pip install -r requirements.txt

如果你打算使用浏览器兜底功能或自动获取 Cookie，再补装 Playwright：

pip install playwright python -m playwright install chromium

第二步：准备配置文件

项目自带一份示例配置，复制一份即可：

cp config.example.yml config.yml

第三步：登录获取 Cookie

抖音的公开接口需要带 Cookie 才能稳定抓取，推荐用工具自带的自动化方式：

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

命令会打开浏览器，你登录一次抖音，回到终端按一下回车，Cookie 就会被自动写入配置。整个过程一分钟左右，比手动从浏览器开发者工具里复制 Cookie 省事得多。

可选：用 Docker 一键部署

不想污染本地 Python 环境？项目提供了 Dockerfile：

docker build -t douyin-downloader . docker run -v $(pwd)/config.yml:/app/config.yml -v $(pwd)/Downloaded:/app/Downloaded douyin-downloader

一张表看懂：哪些链接可以直接抓

工具的入口是一个链接，不同的链接类型对应不同的抓取方式：

链接形式	抓取内容
`/video/{aweme_id}`	单个视频
`/note/{note_id}`、`/gallery/{note_id}`	单个图文
`/collection/{mix_id}`、`/mix/{mix_id}`	单个合集
`/music/{music_id}`	单个音乐（优先原声，缺失时回退到该音乐下的首条作品）
`v.douyin.com/...`、`v.iesdouyin.com`	短链自动解析，无需先手动跳转
`/user/{sec_uid}`	作者主页批量下载
`/user/self?showTab=favorite_collection`	当前登录账号的收藏夹

先看一个最简单的用法——下载单个视频，在config.yml里写：

link: - https://www.douyin.com/video/7604129988555574538 path: ./Downloaded/ music: true cover: true json: true

然后执行：

python run.py -c config.yml

工具会同时保存视频文件（自动挑选无水印源）、封面、背景音乐和一份完整的 JSON 元数据。命令行里会实时滚动进度条，抓完的文件按"日期_标题_作品ID"的格式存放在./Downloaded/下。

进阶玩法：作者主页的四种批量模式

真正体现"批量"威力的是作者主页抓取。把link换成用户主页地址，再用mode声明要抓哪几类内容：

link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx path: ./Downloaded/ mode: - post - like - mix - music number: post: 50 # 作品数量，0 表示全量 like: 0 mix: 10 music: 5 thread: 5 retry_times: 3

四种模式的含义分别是：

post：作者发布的所有作品
like：作者点赞过的作品
mix：作者创建的合集
music：作者使用过的音乐原声

多个模式可以同时开启，同一个作品在跨模式时会被自动去重，不会重复下载。number里填0表示不限制数量、全量抓取。

如果你想备份的是自己收藏的内容，把链接换成/user/self?showTab=favorite_collection，再单独使用collect或collectmix模式即可。注意：收藏夹模式必须单独使用，不能和post、like这些模式混在一起。

除了配置文件，命令行也可以临时追加参数，方便单次操作：

python run.py -c config.yml \ -u "https://www.douyin.com/video/7604129988555574538" \ -t 8 \ -p ./Downloaded

其中-u追加链接（可重复传）、-t指定并发数、-p指定输出目录。

让文件井井有条：命名模板与目录策略

批量下载最怕"一锅粥"，好在工具的命名规则是完全可以自定义的。配置文件里的filename_template支持一组白名单变量：

{date}发布日期、{year}、{month}、{day}、{time}
{author}作者昵称、{author_id}作者 ID
{title}作品标题、{id}作品 ID
{type}、{mode}、{timestamp}等辅助字段

一个常用示例：

filename_template: "{date}_{author}_{title}_{id}" author_dir: "nickname_uid" folderstyle: true

author_dir控制作者目录的命名方式，可选nickname（直观）、sec_uid（稳定唯一）、nickname_uid（既直观又唯一），默认是nickname
folderstyle: true时，每个作品会单独建一个子文件夹，视频、封面、音乐、JSON 都放在一起

抓取完成后的目录结构大致是这样的：

Downloaded/ └── 作者名/ └── post/ └── 2024-02-07_作品标题_aweme_id/ ├── ...mp4 ├── ..._cover.jpg ├── ..._music.mp3 └── ..._data.json

这套结构配合 SQLite 里的下载历史，等于给自己建了一个轻量级的本地作品档案库。如果想控制下载范围，还可以用start_time/end_time做时间过滤，或开启increase.post: true只增量抓取新作品——这些配置在douyin-downloader/config/目录下都能找到对应的默认值定义。

常见卡点排查：翻页风控、Cookie 失效与重复下载

为什么只能抓到 20 条作品？

这是抖音翻页风控的典型表现。工具提供了浏览器兜底策略，在 API 分页受限时会自动拉起浏览器继续滚动加载。需要确认两点：

browser_fallback: enabled: true headless: false

当浏览器窗口弹出来时，手动完成页面上的滑块或验证码，不要急着关窗口，让工具自己跑完再关闭。

Cookie 失效了怎么办？

重新执行一次 Cookie 获取命令即可：

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

文件明明存在，为什么不会重新下载？

工具通过"数据库记录 + 本地文件"双重检查判断是否跳过。要强制重新下载，需要同时清理两处：删除本地文件（文件名里包含aweme_id的文件夹），再删除数据库记录：

sqlite3 dy_downloader.db "DELETE FROM aweme WHERE aweme_id = '<aweme_id>';"

如果想全部从头来过，删掉Downloaded/目录和dy_downloader.db文件即可。注意：只删数据库不删文件不会触发重下，因为程序会扫描本地文件名做去重。

进度条刷屏怎么处理？

默认progress.quiet_logs: true已经会在进度阶段静默日志。排查问题时可以临时加--show-warnings或-v显示更详细的日志。

把它变成自动化流水线：定时任务、通知与 REST API

手动跑命令只适用于临时需求。对于"每天自动更新博主最新作品"这类场景，可以把它挂进系统定时任务。

Linux / macOS 用 crontab，每天凌晨 2 点执行：

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

Windows 用户则在任务计划程序里新建一个任务，执行同样的命令即可。

任务跑完后，想第一时间知道结果？配置通知推送，支持 Bark、Telegram 和企业微信/飞书/钉钉的 Webhook：

notifications: enabled: true on_success: true on_failure: true providers: - type: bark url: https://api.day.app/YOUR_DEVICE_KEY sound: bell - type: webhook url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx

如果你想把下载能力集成进自己的系统，可以启动 REST API 服务模式：

pip install fastapi uvicorn python run.py --serve --serve-port 8000

服务提供几个核心接口：POST /api/v1/download提交下载链接并返回任务 ID，GET /api/v1/jobs/{job_id}查询任务状态，GET /api/v1/health做健康检查。完成态的任务会自动按 TTL 和数量上限清理，正在执行的任务永远不会被裁掉。

容易被忽略的彩蛋功能

除了下载本身，工具还藏了不少实用功能，值得逐个试一遍：

热搜榜快照：python run.py --hot-board 30 -p ./Downloaded，把当日抖音热搜导出成 JSONL 文件，做舆情分析很方便
关键词搜索：python run.py --search "猫咪" --search-max 100 -p ./Downloaded，按关键词搜索作品并导出结果
评论采集：在配置里开启comments.enabled: true，下载的同时按作品抓评论（可含二级回复），输出*_comments.json
视频转写：配置transcript.enabled: true并填好 OpenAI API Key，视频下载后自动生成 txt / json 格式的文字稿，做内容检索和二次编辑非常实用
直播录制：链接填live.douyin.com/{room_id}，可录制 FLV / HLS 直播流，主播下播时已录数据会保留