douyin-downloader完整使用指南:免费无水印批量下载抖音视频,从安装到直播录制的终极教程
每次刷到喜欢的抖音视频,你是不是都要经历一套熟悉的操作:复制链接、打开某个去水印网站、等待解析、手动保存?麻烦倒也罢了,真遇到想收藏一位博主全部作品、或者下载一段直播回放时,这类网站几乎都无能为力。douyin-downloader 正是为解决这些场景而生的开源抖音批量下载工具——免费、去水印、支持视频/图文/合集/音乐,还能批量下载作者主页、录制直播并自动去重。这篇指南会用「三个痛点问题」贯穿始终,带你从安装配置一路走到进阶玩法,读完就能立刻上手。
三个问题:为什么收藏抖音内容这么麻烦?
在正式介绍工具之前,先来对号入座,看看你是不是也有过这些困扰:
- 问题一:想要无水印高清视频,却不想用那些又慢又要付费的第三方网站。
- 问题二:想把喜欢博主的作品、点赞、合集一次性存下来,却只能一条条手动点。
- 问题三:批量下载经常断在中途,重跑一遍又全部重复下载,文件乱成一团。
这三个问题,恰好对应了 douyin-downloader 最核心的三项能力:无水印高清下载、作者主页批量下载、数据库自动去重。下面我们就从零开始,一步步把它们全部解决。
快速认识:douyin-downloader 是什么
简单说,它是一个运行在命令行里的抖音下载引擎:你把链接交给它,它负责把视频、封面、音乐、元数据、评论全部拉回本地,并整理成清晰的目录结构。项目主页的一句话概括是「抖音批量下载工具,去水印,支持视频、图集、合集、音乐」。
它能处理的内容类型,一张表就能看明白:
| 内容类型 | 链接形式 | 说明 |
|---|---|---|
| 单个视频 | /video/{id} | 自动选无水印源 |
| 单个图文 | /note/{id}、/gallery/{id} | 图片作品 |
| 单个合集 | /collection/{id}、/mix/{id} | 按合集下载 |
| 单个音乐 | /music/{id} | 优先原声文件 |
| 用户主页 | /user/{sec_uid} | 批量下载作品/点赞/合集/音乐 |
| 收藏夹 | /user/self?showTab=favorite_collection | 下载自己收藏的作品与合集 |
| 直播 | live.douyin.com/{room_id} | 实时录制直播 |
| 短链接 | v.douyin.com/... | 自动解析跳转 |
此外它还内置了进度条展示、失败重试、速率限制、下载完整性校验、浏览器兜底等工程化能力——也就是说,它不是一个「能用就行」的脚本,而是按长期维护标准打磨的工具。
最快上手路径:10分钟完成第一次抖音无水印下载
先不聊那些花哨功能,我们先把第一个视频下载下来。整个过程只需要四步。
第1步:获取项目代码
打开终端,克隆仓库并进入项目目录:
git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader
cd douyin-downloader
第2步:安装依赖
项目要求 Python 3.8 及以上版本,然后安装依赖:
pip install -r requirements.txt
如果你之后想用「浏览器兜底」或「自动获取 Cookie」功能,再多装一个 Playwright:
pip install playwright
python -m playwright install chromium
小贴士:这两项不是必装项。只想下载单个视频的话,到第3步手动粘贴 Cookie 就能跑通。
第3步:配置 Cookie(关键一步)
抖音要求登录态才能访问内容,所以需要把浏览器里的 Cookie 交给工具。工具提供了三种方式,按优先级从高到低:
方式一:自动获取(最推荐)。运行项目自带的抓取脚本:
python -m tools.cookie_fetcher --config config.yml
它会自动打开浏览器跳转到抖音登录页,你登录完成后回到终端按一下回车,Cookie 就会自动写入配置文件。
方式二:粘贴整串 Cookie。从浏览器开发者工具里复制完整的 Cookie 字符串,直接在配置文件里写成:
cookies: "msToken=xxx; ttwid=xxx; odin_tt=xxx; ..."
方式三:键值对填写。把 Cookie 拆开逐项填入:
cookies:
msToken: YOUR_MS_TOKEN
ttwid: YOUR_TTWID
odin_tt: YOUR_ODIN_TT
passport_csrf_token: YOUR_CSRF_TOKEN
sid_guard: YOUR_SID_GUARD
第4步:编辑配置并运行
先复制配置模板:
cp config.example.yml config.yml
编辑 config.yml,把想下载的链接填进去:
link:
- https://www.douyin.com/video/7604129988555574538
path: ./Downloaded/
music: true
cover: true
json: true
然后运行:
python run.py -c config.yml
看到进度条跑起来,就说明第一次下载成功了。控制台会清晰展示配置信息、作品数量和下载进度:
核心能力拆解:三个问题逐一击破
工具跑通了,我们来深入看看开篇那三个问题分别是怎么解决的。
问题一:无水印与最高清是如何保证的
这是很多人最关心的。douyin-downloader 在这件事上做了两层保障:
第一层,优先选取无水印视频源。 拿到作品信息后,工具会主动筛选无水印的播放地址,而不是无脑下载页面里的默认流。
第二层,按码率自动挑选最高清。 抖音返回的 video.bit_rate 数组里包含多个清晰度版本,工具会逐一比较,自动选择码率最高的一档。也就是说,同一个视频,你拿到的往往是可用的最优画质。
下载时除了视频本体,还可以顺带保存封面、音乐(原声)和 JSON 元数据,全部由 music、cover、json 三个开关控制,默认开启。
问题二:作者主页批量下载的配置方法
这是 douyin-downloader 最出彩的场景。想把一位博主的作品全部搬回本地,只需要把链接换成主页地址,并声明下载模式:
link:
- https://www.douyin.com/user/MS4wLjABAAAAxxxx
mode:
- post # 发布作品
- like # 点赞作品(可选)
- mix # 合集(可选)
- music # 音乐原声(可选)
number:
post: 50 # 0 表示不限制数量
like: 20
mix: 10
music: 10
几个实用细节:
- 跨模式自动去重:同一个作品出现在「发布」和「点赞」里时,只下载一次,不会重复占空间。
- 时间过滤:通过
start_time/end_time(格式YYYY-MM-DD)可以只下载某个时间段内的作品。 - 置顶作品开关:默认不下载作者主页的置顶作品,需要的话把
download_pinned: true打开。 - 收藏夹下载:用
/user/self?showTab=favorite_collection配合mode: collect/collectmix,可以把你自己收藏的作品和合集批量拉下来(注意该模式必须单独使用)。
下载完成后,文件会按「作者 → 模式 → 日期_标题_ID」的层级自动归类,每一个作品一个文件夹,视频、封面、音乐、元数据一目了然:
问题三:断点续传、增量下载与自动去重
批量下载最怕两件事:中断和重复。douyin-downloader 用「数据库 + 本地文件」双重检查来解决。
- SQLite 去重:开启
database: true后,每次下载都会记录到本地数据库(默认dy_downloader.db)。再次运行时,已下载的作品会被自动跳过。 - 增量下载:配合
increase配置,可以实现「只下载新作品」:
increase:
post: true
like: true
database: true
- 完整性校验:下载时会比对 Content-Length,发现文件不完整会自动清理并重试,不会把残缺文件留在磁盘上。
- 失败重试:遇到网络波动,内置的指数退避重试(1秒、2秒、5秒)会自动兜底,
retry_times控制重试次数。
文件名还可以用模板自定义,支持 {date}、{title}、{id}、{author}、{mode} 等 15 种变量,要求模板中至少包含 {id} 以避免重名覆盖:
filename_template: "{date}_{title}_{id}"
folder_template: "{date}_{title}_{id}"
进阶玩法:把下载器变成内容管理工具箱
基础功能熟悉之后,你会发现这个工具还能承担更多任务。
抖音直播实时录制
把链接换成直播间地址,就能实时录制直播内容:
link:
- https://live.douyin.com/123456789
live:
max_duration_seconds: 3600 # 0 表示录到主播下播
chunk_size: 65536
idle_timeout_seconds: 30
录制的 FLV 文件会保存到 Downloaded/{作者}/live/ 目录下。最贴心的是,主播下播、网络空闲或手动中断时,已录制的字节都会被保留,不会白录:
评论采集与热搜关键词
需要分析视频评论?开启评论采集即可,每个作品旁会生成 *_comments.json:
comments:
enabled: true
include_replies: false # true 会额外拉取二级回复
max_comments: 500
page_size: 20
还可以直接拉取抖音热搜榜或按关键词搜索作品,结果导出为 JSONL:
python run.py --hot-board 30 -p ./Downloaded
python run.py --search "猫咪" --search-max 100 -p ./Downloaded
下载完成通知推送
大批量下载时没必要一直盯着终端,配一个完成通知即可:
notifications:
enabled: true
providers:
- type: bark
url: https://api.day.app/YOUR_DEVICE_KEY
- type: telegram
bot_token: "123456:ABC..."
chat_id: "987654321"
支持 Bark、Telegram 和 Webhook(企业微信、飞书、钉钉的机器人地址同样可用),多个 provider 会并发推送。
视频转写
想把下载的视频转成文字稿?开启转写功能即可,会生成 xxx.transcript.txt 和 xxx.transcript.json 两个文件:
transcript:
enabled: true
model: gpt-4o-mini-transcribe
api_key_env: OPENAI_API_KEY
密钥推荐用环境变量提供:export OPENAI_API_KEY="sk-xxxx"。注意转写目前只对视频作品生效。
REST API 服务模式
如果你想把下载能力集成到自己的系统里,项目还提供了 REST API 模式:
pip install fastapi uvicorn
python run.py --serve --serve-port 8000
启动后可用 POST /api/v1/download 提交下载任务,用 GET /api/v1/jobs/{job_id} 查询任务状态,非常适合做自动化二次开发。
桌面版 Douzy
不习惯命令行也没关系,项目基于同一套后端提供了桌面客户端 Douzy(目前内测中)。粘贴链接即可自动检测内容类型并选择下载范围:
桌面版还内置任务中心,可以实时跟踪每个任务的下载进度和成功/失败统计,支持任务取消与日志导出:
避坑指南:高频报错与修复方法
用了别人没遇到过的坑,这里提前帮你排掉。
只能抓到20条作品怎么办?
这是抖音翻页风控的常见现象,不是工具坏了。确认浏览器兜底已开启:
browser_fallback:
enabled: true
headless: false
浏览器弹窗出现后,手动完成验证再关闭窗口,验证通过后下载会继续。注意浏览器兜底目前只针对 post 模式做了完整验证,like/mix/music 主要依赖 API 正常分页。
Cookie失效了怎么办?
Cookie 有有效期,失效后重新获取即可:
python -m tools.cookie_fetcher --config config.yml
项目还内置了自动重新登录机制:运行中检测到登录态失效,会尝试打开浏览器引导重新登录,成功后自动重试。
进度条刷屏怎么办?
默认配置 progress.quiet_logs: true 会在进度阶段静默日志,减少刷屏。调试时才临时加 --show-warnings 或 -v 查看详细信息。
如何重新下载某个作品?
去重机制意味着「只删数据库」不会触发重新下载(本地文件里有 ID 也会被识别)。要彻底重下,需要同时清理文件与数据库记录:
sqlite3 dy_downloader.db "DELETE FROM aweme WHERE aweme_id = '作品ID';"
下载速度太慢怎么办?
三个参数帮你提速:
thread: 8 # 增加并发下载数
max_per_second: 3 # 调整每秒请求频率
proxy: "http://127.0.0.1:7890" # 网络不佳时走代理
写在最后
回到开篇的三个问题,现在你已经有了一套完整的答案:想要无水印高清视频,douyin-downloader 会自动挑选无水印最高码率源;想要批量收藏博主内容,主页链接加 mode 配置一次搞定;担心中断和重复,SQLite 去重、增量下载和完整性校验已经替你兜底。
给你的行动建议很简单:先下载一个视频跑通流程,再试试作者主页批量下载,最后按需开启直播录制或评论采集。每多用一个功能,你对这个工具的掌控感就会更强一分。
最后提醒一句:本工具仅用于技术研究、学习交流与个人数据管理,请尊重创作者版权与他人隐私,在合法合规的前提下使用。
项目地址:git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader,开箱即用,MIT 协议开源。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/gitblog_00610/article/details/163794129








