douyin-downloader 抖音批量下载实操指南：50 条作品一次跑完，配置、风控与去重全讲清

douyin-downloader 抖音批量下载实操指南：50 条作品一次跑完，配置、风控与去重全讲清

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

归档一个抖音博主的 200 条作品，手动路线是逐条打开、保存、重命名，耗时以小时计。douyin-downloader 把这件事压缩成一条命令：Python 实现的抖音批量下载工具（MIT 协议，Python 3.9+），粘贴主页链接后自动抓取作品列表，并发下载无水印视频，可附存封面、音乐、头像和原始 JSON，并用本地 SQLite 数据库加文件名双重去重。它适合个人收藏归档、素材收集和内容分析三类用户。本文以"批量下载某位博主最近 50 条作品"为主线，从安装讲到跑完，顺带讲清风控应对和它做不到的事。

能力总览：哪些抖音内容能落到本地

先给一张清单，看你要的东西在不在范围内：

命令行侧还能导出数据而不是媒体：python run.py --hot-board 30和python run.py --search "关键词" --search-max 50会把热搜榜和搜索结果写成 JSONL，直接进分析流程。同一个后端还衍生了桌面客户端 Douzy（内测中），粘贴链接即开始下载，任务中心里看进度、重试失败项。

清单之外先说结论：CLI 只支持抖音国内版，其余平台要走 Douzy。下面从装环境开始。

安装与 Cookie 获取：唯一需要碰浏览器的环节

要求 Python 3.9+，Windows、macOS、Linux 均可。克隆仓库并装依赖：

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

登录态是最关键的一步，但不用手动从浏览器复制。项目自带获取脚本（cookie_fetcher）：

pip install playwright python -m playwright install chromium cp config.example.yml config.yml python -m tools.cookie_fetcher --config config.yml

会弹出一个浏览器窗口，正常登录抖音，回到终端按 Enter，Cookie 就写进config.yml了。playwright 依赖同时服务于后文的"浏览器兜底"翻页，建议一并装上。

批量下载博主作品：config.yml 里改三处

把 config.example.yml 复制成config.yml后，只需关注这几行：

link: - https://www.douyin.com/user/YOUR_SEC_UID mode: [post] number: post: 50 # 0 表示全量 increase: post: true # 跳过已下载作品

运行：

python run.py -c config.yml

文件落在path指定的目录，默认./Downloaded/，结构如下：

Downloaded/ ├── download_manifest.jsonl └── 作者名/ └── post/ └── 2024-02-07_作品标题_aweme_id/ ├── 2024-02-07_作品标题_aweme_id.mp4 └── ..._data.json

三个命名细节值得留意：日期前缀取作品发布时间（create_time）而非下载时间，按目录名排序就是按发布时间排序；文件名尾部带aweme_id，两条作品不会重名覆盖；默认命名模板是{date}_{title}_{id}，可在filename_template中改，但必须保留{id}。Downloaded/根目录还有一份 append-only 的download_manifest.jsonl，每个作品追加一行，含date、tags、file_paths等字段，想建索引直接读它。

同后端逻辑在 Douzy 桌面版里长这样：选中内容类型、填数量上限、提交任务，右侧任务中心看进度。

时间范围筛选：只捞 2024 年的作品

配置里加两行日期（YYYY-MM-DD，含结束日期当天）：

start_time: "2024-01-01" end_time: "2024-12-31"

配合increase.post: true，就是标准的增量姿势：每周跑一次，只拉新发布、未下载过的作品，不用全量重拉。需要强制重下时，把increase.post设为false即可覆盖当前筛选范围内的文件，不必删数据库。

可选产物：封面、音乐、评论、原始 JSON

默认只下视频本体，其余产物按需打开。在config.yml中把music、cover、avatar、json设为true，对应的_music.mp3、_cover.jpg、_avatar.jpg、_data.json会存进与视频同一目录；video_quality默认highest（最高转码档），改original会多一次探测请求去尝试上传原片，失败自动回退。

想连数据一起采，打开评论开关：

comments: enabled: true include_replies: true max_comments: 0 # 0 表示不限

每个作品额外生成一份*_comments.json，含二级回复。转写（transcript）、完成通知（notifications）也是同风格的可选开关，完整字段都在 config.example.yml 里。

稳定性机制：默认值已经替你调好

上百条作品时，"逐条手动下"和"并发自动下"的耗时差距是几倍量级，差别来自这几个默认值：thread: 5（5 个作品并发，可用-t覆盖）、限速默认 2 请求/秒；单条失败按 1s、2s、5s 退避自动重试 3 次（retry_handler）；下载完成后用 Content-Length 核对文件大小，不完整的文件会被清掉重下，配合redownload_missing_files: true的默认行为，你不需要翻找 0 字节坏文件。去重则是"SQLite 记录 + 文件名 aweme_id"双重判断：默认database: true，库文件为dy_downloader.db，同一任务跑第二遍基本整批跳过，这个任务可以放心挂着当定期任务。

默认值讲完了，接下来是跑不顺时的两件事：风控和常见问题。

风控与常见问题的处理

先说必须知道的现状（README 原文立场）：抖音接口风控目前会拦截 CLI 下载单个视频/图文、合集、音乐、点赞和收藏，主页作品可尝试 Playwright 浏览器兜底，但不保证成功。所以遇到"只抓到 20 条左右就停"，多半是翻页被风控：保持browser_fallback.enabled: true且headless: false（两者默认如此），弹出浏览器窗口时手动完成验证，别急着关。

其余三件小事：Cookie 失效、请求频繁失败，重跑一次python -m tools.cookie_fetcher --config config.yml，两分钟解决；速度不满意，先把thread降到 2-3，其次换非高峰时段，用了代理先确认代理本身稳定；想排查就加-v看详细日志，平时quiet_logs: true默认已静默进度刷屏。

边界：CLI 不做什么

明确不支持的：CLI 直接下载其他平台（那是 Douzy 内测中工作台的事）；浏览器兜底目前只完整支持post模式，like/mix/music主要依赖接口分页正常；直播录制属实验功能，HLS 源保存的是播放列表而非可直接播放的视频。合规上，项目声明用途限于技术研究、学习交流与个人数据管理——下载他人作品二次发布、采集隐私内容、绕过限制做商业用途都不合适，平台接口变动导致功能失效也属正常技术风险。

跑通首单只需三步：克隆仓库并装依赖；运行python -m tools.cookie_fetcher --config config.yml完成登录；把主页链接和mode: [post]写进config.yml，然后python run.py -c config.yml。剩下的事，交给 5 个并发和自动重试。

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