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 是一个值得试的命令行工具：它从抖音服务端直接拉取原始文件，做抖音无水印下载，视频、图文、合集、音乐和作者主页作品都可以批量抓下来。整体是 Python 加 YAML 配置文件的形态，内置并发、重试和去重。这篇笔记按从零跑通到日常使用的顺序讲一遍，并附上容易踩到的坑。

它能做什么，边界在哪里

使用方式很直接：给它一条抖音链接，它把对应内容下载下来并把文件整理好。支持的链接类型包括单个视频、单个图文、单个合集、单个音乐、短链和作者主页。主页场景通过配置文件里的mode字段选模式：post（发布作品）、like（点赞）、mix（合集）、music（音乐），另外还能抓取当前登录账号的收藏夹与收藏合集，这两种 collect 模式需要单独使用，不能和别的模式混配。

几个值得了解的机制：

无水印优先：自动选无水印源，并从码率数组里挑最高码率
双重去重：SQLite 数据库加本地文件检查，重跑时跳过已有作品，不重复占盘
并发与限速：默认 5 线程、每秒 2 个请求，失败按指数退避重试
附加资源：封面、原声音乐、作者头像、JSON 元数据可开关，评论采集、直播录制、视频转写也都是可选项

对不写代码的人来说，这个工具的价值集中在两件事：把某人的作品批量拿下来，以及让下载内容有条理地摆放。

最短跑通路径：安装、Cookie 与首次运行

安装依赖并获取 Cookie

需要 Python 3.8 以上，Windows、macOS、Linux 都行。克隆仓库并装依赖：

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

抖音的内容接口需要登录态，所以下一步是拿 Cookie。项目自带自动获取脚本（先装上可选依赖 playwright 和 chromium 浏览器），运行后弹出浏览器，用手机登录，回终端按回车，Cookie 就写进配置文件了：

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

Cookie 的存放与 token 刷新逻辑在 auth/ 模块里，平时不用手动动它。

最小配置文件

按官方文档，把仓库里的 config.example.yml 复制为 config.yml。最小可用配置只需要这几个字段：

link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx path: ./Downloaded/ mode: - post thread: 5 database: true

link是下载目标，mode选主页模式，thread是并发数，database: true打开去重和下载历史。保存后执行python run.py -c config.yml即可开始任务，也可以用命令行-u直接追加链接、用-t调并发。

一次运行之后发生了什么：文件、去重与进度

目录结构与文件命名

folderstyle: true（默认）时，文件按"作者名 → 模式 → 单个作品子目录"组织，文件名带作品发布日期、标题和 aweme_id。一个作品的目录里并排放着视频、封面、音乐、头像和 JSON 元数据，Downloaded 根目录还有一份download_manifest.jsonl清单，每个作品一行，方便日后批量查找。

终端里用进度条展示总体进度，progress.quiet_logs默认开启，下载阶段会压住日志输出，避免刷屏。

两个常见坑

坑一：只能抓到二十来条作品。这是翻页风控的典型表现。把配置里browser_fallback.enabled保持true、headless保持false，弹出浏览器窗口后手动完成验证码，别立刻关窗，否则兜底就白开了。

坑二：Cookie 失效或大量 403。多数情况是 Cookie 过期，重跑上面的获取命令更新即可。另外要留意：截至本文写作时，抖音已对作品详情、合集、音乐等接口上线风控门禁，CLI 里直接请求单个作品、合集、音乐类链接可能拿不到数据，主页作品则依赖浏览器兜底。这一限制的背景在 README.zh-CN.md 的"限制说明"一节写得比较细；同后端还有一款内测中的桌面版 Douzy，能绕过其中部分限制，值得一试：

长期使用前的注意事项

几个进阶配置值得知道

日常用得最多的几项都在配置文件里：

number: post: 50 increase: post: true start_time: "2024-01-01" end_time: "2024-12-31"

前两段的意思是只取前 50 条发布作品、后续运行只取新增；后两段按发布日期过滤。此外comments.enabled: true会为每个作品生成评论 JSON；命令行还带--hot-board和--search两个小工具，分别抓热搜榜和按关键词搜作品，输出都是 JSONL。想了解内部结构（URL 解析、下载器工厂、存储层），PROJECT_SUMMARY.md 里有现成的梳理，看一遍就够。