抖音无水印批量下载：从 Cookie 配置到主页归档的运行手册
项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader 把某位创作者的全部作品按日期归档到本地，需要的是可靠的抖音无水印批量下载工具，而不是逐个视频截图。douyin-downloader 面向这一场景：视频、图文、合集、音乐与直播均可抓取，内置进度展示、重试、SQLite 去重与浏览器兜底，适合个人收藏、素材整理和内容研究。
能力速览：覆盖单条抓取到主页归档的主要场景
抖音接口要求有效登录态，工具内置无水印源选择、进度展示、指数退避重试与文件完整性校验，常用能力与对应入口如下：
| 功能 | 适用场景 | 对应命令/配置项 |
|---|---|---|
| 单条内容下载 | 保存指定视频、图文、合集、音乐 | run.py -u "链接" |
| 用户主页批量下载 | 归档某位作者的全部作品 | mode: [post] + number.post |
| 增量存档 | 定期只拉取新作品 | increase.post: true（依赖 database: true） |
| 时间范围筛选 | 只下载某时间段发布的作品 | start_time / end_time |
| 直播录制 | 留存整场直播，下播保留已录字节 | live.douyin.com/{room_id} + live.* |
| 热搜与关键词导出 | 数据调研，结果落 JSONL | --hot-board N / --search 关键词 |
| 画质与代理 | 控制流量与网络出口 | video_quality / proxy |
| 完成通知 | 批量任务跑完推送到手机 | notifications.* |
环境准备与首次运行：克隆、装依赖、配 Cookie、跑通第一条
环境要求 Python 3.8+，在 macOS、Linux、Windows 均可执行。
git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader
cd douyin-downloader
pip install -r requirements.txt
cp config.example.yml config.yml
执行后得到完整仓库、运行依赖与一份可直接修改的 config.yml。
Cookie 是鉴权前提，config.yml 的 cookies 段必须有效。自动获取需先安装 Playwright 并执行：
pip install playwright && python -m playwright install chromium
python -m tools.cookie_fetcher --config config.yml
该命令弹出浏览器登录页，扫码登录完成后回到终端按 Enter，程序把 msToken、ttwid、odin_tt、passport_csrf_token 等字段写回配置文件，无需手工填写。已有 Cookie 则从浏览器开发者工具复制后填入 cookies 段，字段名与自动获取结果一致。
首次运行用配置驱动：
python run.py -c config.yml
示例配置默认包含一个作者主页链接和 number.post: 1。执行后终端出现下载进度，Downloaded/ 下生成首个作品目录；出现文件即说明 Cookie、下载、去重、命名链路全部就绪。
按任务组织的使用方法：三条命令覆盖常用下载任务
抖音单条视频下载命令
python run.py -u "https://v.douyin.com/xxxxx" -p ./Downloaded
运行该命令会解析短链、自动识别资源类型并选择无水印源，执行后在 Downloaded/ 下得到视频文件及对应的元数据、封面等附属产物。
抖音主页作品批量下载
在 config.yml 中写入目标作者链接后运行 python run.py -c config.yml：
link:
- https://www.douyin.com/user/MS4wLjABAAAAxxxx
mode:
- post
number:
post: 0
执行后作品按「作者昵称/日期_标题_作品 ID」结构落入 Downloaded/，number.post: 0 表示全量下载。SQLite 数据库记录已下载的作品 ID，并与本地文件双重去重，重跑同一任务会自动跳过已存在的作品。API 翻页受限时，browser_fallback 启动有头浏览器页面，靠真实滚动加载作品列表；期间弹出验证码需手动完成，验证通过后翻页继续。
桌面版 Douzy 任务中心：主页与合集的批量下载任务按状态归档，失败项可单独重试
按时间范围筛选作品
start_time: "2026-01-01"
end_time: "2026-06-30"
配置后运行，只保留发布日期在该区间内的作品；与 increase.post: true 组合可实现按时间窗口的定期存档。
常用配置与调优：并发、画质、时间窗三个开关决定批量行为
thread 控制并发下载数，默认 5。网络较慢或失败率上升时降到 2～3；调高并发会增加触发限速与失败重试的概率。
video_quality 决定码率档位：highest 在转码阶梯中选最高档，不发探测请求；original 为每条作品额外发起一次原片探测，失败时回退最高转码档；lowest 或指定分辨率用于省流量场景。
start_time / end_time 按发布日期过滤作品，配合 increase.post: true 实现增量存档，database 需保持 true 以保证去重与增量判断生效。
问题排查速查：四类常见故障对照处理
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 接口报登录失效 | Cookie 过期 | 重跑 python -m tools.cookie_fetcher --config config.yml 重新获取 |
| 作品列表停在 20 条左右 | 翻页触发风控 | 保持 browser_fallback.enabled: true、headless: false，手动完成弹出的验证 |
| 单条视频链接报 403 | 2026-09 起 Argus 风控拦截 API 直连 | 改用桌面版 Douzy，或从主页批量入口获取该作品 |
| 下载中断后重跑 | 任务未完成 | 增量模式与数据库自动跳过已完成作品，live 场景 .tmp 分段会提升为正式文件 |
本工具仅适用于个人学习、研究与个人数据管理，下载内容请勿二次传播。完整参数见 config.example.yml 与 README.zh-CN.md。现在打开终端，从单条链接开始跑一次，验证全链路可用。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
