douyin-downloader 上手指南：10 分钟完成抖音批量下载，无水印保存全流程

【免费下载链接】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 做的事很直接：粘一个博主主页链接，作品就去水印整批存到本地、按作者分好文件夹。想长期归档创作者内容的人适合它，从装依赖到跑通第一次下载，10 分钟以内。

运行前确认环境：Python 3.9+ 即可

• 需要 Python 3.9+，Windows、macOS、Linux 三个平台都能跑
• 核心依赖全部列在 requirements.txt 里，一条 pip 命令装完
• Cookie 不用自己翻找字段，内置脚本在首次登录时自动写入配置；Cookie 自动获取与翻页兜底还依赖 Playwright 拉起的浏览器运行时

这张图来自 Douzy 桌面版，是同一后端的图形化形态：界面里勾选作品、喜欢、合集、音乐，设好各模式的数量上限，粘上链接就能开始下载，完全不用手写 YAML。本文讲的是命令行版，底层能力是同一套。

第一次下载怎么开始

先把代码拉到本地，顺手把依赖装齐：

git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader pip install -r requirements.txt pip install playwright && python -m playwright install chromium

最后两条装的是浏览器及其运行时。跑完这组命令后，机器上同时具备核心依赖和兜底用的 Chromium；少装它们，Cookie 自动获取和翻页受限时切换浏览器继续拉的功能都用不了。

配置模板就在仓库根目录，复制一份出来当实际文件：

cp config.example.yml config.yml

Windows PowerShell 里换成Copy-Item config.example.yml config.yml就行。每个字段的写法、可选值有哪些，翻一遍 config.example.yml 就有答案。

拿到配置文件后，先取 Cookie 再改参数：

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

这条命令会弹出一个浏览器窗口，登录抖音后回到终端按 Enter，脚本就把 Cookie 写进config.yml，直到失效前只需做一次。接下来打开配置改四处就够跑：link填目标博主的主页链接，path: ./Downloaded/定落盘目录，mode: [post]表示只拉作品，number下的post: 50控制数量，写0就是全量拉取。保存后直接运行python run.py -c config.yml启动。终端里会滚动出进度条，失败项按retry_times自动重试，全部完成后文件就落在Downloaded/里。想看详细日志加-v，想在命令行临时追加链接用-u。

下载的文件去哪了

folderstyle: true是默认值，落盘结构是"作者目录 / 模式目录 / 作品目录"三层：

Downloaded/ └── 作者昵称/ └── post/ └── 2024-06-15_舞蹈教学_7604129988555574538/ ├── 2024-06-15_舞蹈教学_7604129988555574538.mp4 ├── 2024-06-15_舞蹈教学_7604129988555574538_cover.jpg ├── 2024-06-15_舞蹈教学_7604129988555574538_music.mp3 └── 2024-06-15_舞蹈教学_7604129988555574538_data.json

默认只生成视频本体，后三个文件要分别打开cover、music、json开关才会出现。

文件夹名和文件名都由filename_template渲染，默认{date}_{title}_{id}，即"日期_标题_作品ID"。日期取作品发布时间create_time，作品缺这个字段时回退成当天日期。模板里为什么非得留着{id}：作者发过标题撞车或同一天多条作品时，没有 ID 兜底就会互相覆盖。

作者那一层默认按昵称建目录，副作用有两个：重名博主的文件会并进同一个文件夹，博主一改名新目录又单独裂出去。想两头都躲开，把author_dir设成nickname_uid，目录名变为"昵称_sec_uid"，直观且稳定。

无水印下载怎么配置：最常调的几个参数

mode一次写多个值时，相同 ID 的作品会自动跨模式去重，不会重复落盘。collect是例外：它必须单独使用，链接固定指向https://www.douyin.com/user/self?showTab=favorite_collection，且只拉 Cookie 所属账号自己的收藏夹。

按需加料：四个进阶能力

只存新作品：增量下载

隔三差五回来看同一个作者、又不想重复下载时，靠它。increase.post默认就是true：每次运行先查数据库和磁盘，已记录且文件还在的旧作品直接跳过，只下新增内容，保持database: true（默认已开）即可生效。反过来把它设为false，会在当前数量与时间筛选范围内重新下载并覆盖旧文件，不用清空数据库。

连同评论和语音文本一起保存

想归档作品下的讨论，或者把口播变成文字时，加上这段：

comments: enabled: true # 每个作品额外生成 *_comments.json max_comments: 500 transcript: enabled: true model: gpt-4o-mini-transcribe response_formats: [txt, json]

max_comments写0就是不限条数；转写只对视频作品生效，图文作品不生成转写文件。转写走 OpenAI，运行前先把密钥挂到环境变量：export OPENAI_API_KEY="sk-xxxx"。完成后每个视频作品目录里会多出一份.transcript.txt与.transcript.json。

翻页被风控时：浏览器兜底 ⚠️

2026-08 起，抖音风控门禁已覆盖多数 CLI 接口，拉取量明显变少时把这条路打开：

browser_fallback: enabled: true headless: false

弹窗里出现验证就手动完成，别急着关浏览器。这个机制目前只对post主页作品场景完整验证过，也不保证一定成功。

下完自动收到通知

长任务挂着跑、人不在电脑前，希望完成时有人知会一声，就配通知：

notifications: enabled: true on_failure: true providers: - type: webhook # 支持 webhook / bark / telegram url: 你的webhook地址

各通道并发推送，单个 provider 挂了不阻塞主下载流程。webhook 可以直接对接企业微信、飞书、钉钉的群机器人。

下载不动，先查这五处

• 只拉得到约 20 条作品—— 翻页触发了风控。确认browser_fallback.enabled: true且headless: false，然后在弹窗里完成验证。
• 报未登录类错误、成片下载失败—— Cookie 失效。重新跑一次python -m tools.cookie_fetcher --config config.yml，登录动作做一遍就好。
• 速度慢、频繁中断—— 网络波动或并发拉太高。thread降到 3，在proxy里填上可用代理。
• 新旧作品互相覆盖—— 命名模板里没留{id}。把filename_template设回"{date}_{title}_{id}"。
• 磁盘被占满—— 全量拉取叠加高画质。用number.post限制数量，start_time/end_time圈定时间，video_quality调低一档。

更多字段和完整命令清单在 README.zh-CN.md 里找；Cookie 脚本的实现在 tools/cookie_fetcher.py。

这个工具定位是个人学习、研究与数据备份。下载内容的版权归创作者所有，再分发之前务必拿到授权，并遵守平台服务协议；平台策略一变、接口跟着调整，属于正常的技术风险。

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