三步跑通 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 就是干这件事的：贴一个主页链接，它自动翻页批量下载作品，支持增量同步和本地去重，全程在你电脑上运行，Cookie 和数据都不出机器。

从安装到跑通：四步完成第一次下载

1️⃣ 装环境

需要 Python 3.9 及以上版本，拉代码后装依赖，再装浏览器内核（登录和浏览器兜底都要用）：

git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader python -m pip install -r requirements.txt python -m pip install playwright python -m playwright install chromium # 安装浏览器内核

验证方式：装完后终端不会报错，python -m playwright相关命令能正常执行。

2️⃣ 拿登录态（新手最容易卡的一步）

抖音接口需要 Cookie 才能调通。先复制一份配置文件，然后跑自带的提取脚本：

cp config.example.yml config.yml python -m tools.cookie_fetcher --config config.yml # Windows PowerShell 用 Copy-Item 复制文件

脚本会弹出浏览器，你手动登录一次抖音，回到终端按 Enter，Cookie 就自动写回config.yml了。如果不想装浏览器，也可以直接从浏览器 F12 的 Cookie 里把字符串复制到配置文件的cookies字段。

3️⃣ 写配置

把config.yml里的示例链接换成目标博主主页，最小可用配置如下：

link: - https://www.douyin.com/user/YOUR_SEC_UID # 博主主页链接，可写多条 path: ./Downloaded/ # 保存目录，不存在会自动创建 mode: [post] # post=作品，也可填 like/mix/music number: post: 10 # 先试 10 条，0 表示不限数量 increase: post: true # 增量模式：跳过已下载过的作品 video_quality: highest # 画质：highest 最高转码档，original 尝试原片 thread: 5 # 并发线程数

link支持主页、单条视频、合集多种链接；number.post控制每个主页最多拉多少条；increase.post配合本地数据库实现只补新内容。

4️⃣ 跑任务

python run.py -c config.yml

终端会实时滚动显示每条作品的进度、成功/失败计数，结束时输出本次统计。想看详细日志就加-v。跑完打开./Downloaded/，文件已经按"作者 / 内容类型 / 作品"分好文件夹，每条作品一个独立目录。

它是怎么工作的：理解流程少走弯路

下载流水线

一次任务按固定顺序执行：读取配置 → 初始化 Cookie 与 API 客户端 → 解析链接类型 → 翻页拉取作品列表 → 按时间/数量筛选 → 并发下载媒体 → 写元数据与下载清单 → 记录 SQLite 历史。每一步失败都有重试，整体流程可在 PROJECT_SUMMARY.md 里核对细节。

输出目录长什么样

folderstyle: true（默认）时，落盘结构固定为三级：

Downloaded/ ├── download_manifest.jsonl # 全量下载清单，每行一条 JSON └── 作者名/ └── post/ └── 2024-02-07_作品标题_aweme_id/ ├── 2024-02-07_作品标题_aweme_id.mp4 ├── ..._cover.jpg # 封面 ├── ..._music.mp3 # 音乐 └── ..._data.json # 元数据

文件名带作品 ID，同标题作品不会互相覆盖；日期取作品发布时间而不是下载时间。

浏览器兜底机制

接口翻页受限时，browser_fallback（默认开启）会让 Playwright 打开真实浏览器滚动主页，采集作品 ID 再补全详情。这是主页批量场景目前的主要可用路径，配置项都在 config.example.yml 里有注释。

数据库去重

database: true时，工具把每条作品的作者、发布时间、保存路径写进本地dy_downloader.db（SQLite），任务级别的成功数也记在download_history表里。查"我到底存过哪些作品"直接查库即可，不用翻文件夹。

配置方法：常用字段速查

完整字段（评论采集、转写、通知、直播录制等可选模块）都带中文注释，见 config.example.yml。

常见问题排查

Cookie 失效了怎么办

现象：大面积失败，日志提示登录态无效。原因：Cookie 过期。解决：重跑python -m tools.cookie_fetcher --config config.yml重新抓取，不要手改已有字段的拼写。

主页只下到了几条

现象：数量明显少于主页实际作品数。原因：接口风控或翻页受限。解决：确认browser_fallback.enabled: true且headless: false，让浏览器窗口在屏幕上完成人工验证；注意 README 里写明，风控更新时更新 Cookie 或反复重试并不一定能解决。

同标题作品互相覆盖

现象：某些作品只剩一个文件夹。原因：自定义命名模板里去掉了{id}。解决：保持默认命名（模板要求至少含{id}），由作品 ID 保证目录唯一。

断网后要不要整批重跑

现象：部分成功、部分失败。原因：网络波动。解决：不用重跑。直接再次运行即可，已存在的非空文件会自动跳过；配合increase.post: true只补缺口。

进阶：让下载自己跑

增量 + 定时

increase.post: true保持默认，Linux/macOS 用 crontab 每天凌晨补一次新增内容：

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

完成通知

notifications模块支持 Bark、Telegram、企业微信 webhook 三种渠道，任务成功或失败时推送到手机，不用盯着终端。

清单复用

download_manifest.jsonl里每条记录带作者、发布日期、标题、标签、文件路径，直接导入表格或笔记软件就能做内容盘点。

适用边界

douyin-downloader 适合两类用法：把关注博主的作品完整搬回本地，以及给内容库做定期增量同步；单条、单合集等场景在平台风控收紧时可能受限，以 README 的"命令行版现状"一节为准。请仅用于个人学习、备份与研究，尊重内容创作者的权益，不用于商业用途或侵权场景；平台规则变化也可能影响部分功能可用性。

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