抖音无水印批量下载工具 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 时，我只想保存一位美食博主最近发的 30 个视频。手动录屏有平台水印，在线解析网站画质压得一塌糊涂，一个个右键保存更是折磨。抱着试试看的心态敲下python run.py -c config.yml，十几分钟后，Downloaded文件夹里整整齐齐躺着 30 个无水印原画质视频、30 张封面和 30 段原声。这篇文章记录的就是我从零上手这款开源工具的完整过程，覆盖安装、配置、进阶玩法和踩坑修复，照着做你也能跑通。
30 秒看懂：它能做什么，适合谁
douyin-downloader 是一款面向实用场景的抖音下载工具，核心能力是去水印批量下载，支持视频、图文、合集、音乐（原声）、作者主页、收藏夹等多种内容类型，并自带进度展示、失败重试、SQLite 去重和浏览器兜底。
| 能力 | 说明 | 适合谁 |
|---|---|---|
| 单个视频/图文/合集/音乐下载 | 粘贴链接即下，自动选无水印高清源 | 普通用户，随手收藏 |
| 作者主页批量下载 | 一次拉取发布、点赞、合集、音乐作品 | 追更博主、素材收集者 |
| 收藏夹下载 | 下载当前登录账号收藏的作品与合集 | 重度用户 |
| 直播录制 | 解析直播流，FLV 保存，下播保留已录数据 | 直播回放收藏 |
| 评论采集 / 热搜 / 搜索 | 导出评论 JSON、热搜榜 JSONL、关键词搜索 | 数据分析爱好者 |
| REST API 服务模式 | 把下载能力封装成 HTTP 接口 | 二次开发者 |
项目同时维护着两套入口：根目录的DouYinCommand.py（V1.0 稳定版，单视频下载最稳）和douyin-downloader/目录下的run.py（功能最全的重构版）。后面我会先讲两条最快路径，再分层递进讲配置。
最快跑通：两条路选一条，五分钟看到第一个视频落地
路径 A：V1.0 稳定版，三步下载单个视频
# 1. 安装依赖 pip install -r requirements.txt这一步把 aiohttp、pyyaml 等核心依赖装进当前 Python 环境，是后续所有命令的前提。
# 2. 复制配置模板并编辑 link 与 path cp config.example.yml config.yml# 3. 运行（默认读取当前目录 config.yml） python DouYinCommand.py把config.yml里link换成你的视频分享短链，程序会自动解析短链、抓取无水印地址并下载到path指定目录。整个流程全自动，几秒完成下载。
路径 B：重构版 run.py，一条命令下载作者主页
# 在 douyin-downloader/ 目录下 pip install -r requirements.txt cp config.example.yml config.yml python run.py -c config.ymlrun.py是重构版主入口，-c指定配置文件。它聚合了批量、去重、重试、浏览器兜底等全部能力，适合作为长期主力工具。
无论走哪条路，你都会在控制台看到类似的进度输出：成功 1/1、用时、保存路径一清二楚。
第一步配置：Cookie 的三种获取方式
抖音需要登录态才能访问内容，Cookie 是运行前提。config.example.yml里写了三种方式，按优先级从上到下：
# 方式一：自动获取（推荐，需要 Playwright） cookies: auto # 方式二：直接粘贴整串 Cookie # cookies: "msToken=xxx; ttwid=xxx; odin_tt=xxx; ..." # 方式三：键值对逐项填写 # cookies: # msToken: xxx # ttwid: xxx # sid_guard: xxx方式一最省事，前提是先装 Playwright：
pip install playwright python -m playwright install chromium然后用项目自带的抓取脚本，扫码登录后自动写入配置：
python -m tools.cookie_fetcher --config config.yml登录抖音网页版后回到终端按 Enter，Cookie 自动落到配置文件里，无需手动复制粘贴。方式二、方式三适合你手里已经有一串有效 Cookie 的情况，注意三选一，不要同时保留。
进阶闯关：从新手到高手的配置递进
新手关：改三个字段，先跑起来
link: - https://www.douyin.com/video/7604129988555574538 path: ./Downloaded/ music: true # 下载背景音乐 cover: true # 下载封面 json: true # 保存元数据 JSON这段配置定义了"下载什么、存到哪、附带哪些资源"。music、cover、json默认都是true，不想存可以改成false。
进阶关：批量与去重
作者主页批量下载是高频场景，配置mode指定内容类型，number限制数量：
link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post # 发布作品；还可写 like(点赞)/mix(合集)/music(音乐) number: post: 50 # 最多 50 个，0 表示全量配合database: true启用 SQLite 去重后，重复运行同一配置只会补下新增内容。再加一句增量开关，就能做到"只下载新作品"：
increase: post: true database: true # 增量模式依赖数据库记录高手关：时间过滤、命名模板与浏览器兜底
长时间挂机收集素材时，建议用时间过滤框定范围，避免把三年老内容全拉下来：
start_time: "2024-01-01" end_time: "2024-12-31"下载后的文件名可以完全自定义，模板变量包括{id}{title}{author}{date}{year}{month}{day}{time}{type}{mode}：
filename_template: "{date}_{title}_{id}" folder_template: "{date}_{title}_{id}" author_dir: "nickname" # 作者目录命名，可选 nickname/sec_uid/nickname_uid注意模板里至少要保留{id}，否则重名作品会互相覆盖。
当 API 翻页被风控、只抓到 20 条时，浏览器兜底会启动真实浏览器帮你继续翻页：
browser_fallback: enabled: true headless: false # 弹窗出现后手动完成验证，别急着关窗口 max_scrolls: 240实战演练：三个真实场景的完整配置
场景一：追更博主，主页全量备份
把一位创作者的发布、点赞、合集、音乐一次拉全，跨模式自动按aweme_id去重，不会重复下载：
link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post - like - mix - music number: post: 0 like: 0 mix: 0 music: 0 path: ./博主备份/下载完你会得到一个按作者、按内容类型分层的目录结构，视频、封面、音乐、元数据 JSON 各归其位：
Downloaded/ └── 博主名/ └── post/ └── 2024-02-07_作品标题_aweme_id/ ├── ...mp4 ├── ..._cover.jpg ├── ..._music.mp3 └── ..._data.json场景二：直播间回放录制
把直播链接放进link，程序自动解析直播流并给出清晰度选项：
python DouYinCommand.py -l "https://live.douyin.com/123456789" -p ./直播存档-l传直播链接，-p指定存档目录。录制参数可在配置里微调，主播下播、网络空闲或手动中断时，已录制的字节都会被保留为正式文件：
link: - https://live.douyin.com/123456789 live: max_duration_seconds: 0 # 0 = 录到主播下播 idle_timeout_seconds: 30场景三：数据分析，热搜榜与关键词搜索
做内容趋势分析时，不需要下载视频本体，只要结构化数据。run.py提供了两个轻量出口：
# 拉取热搜榜前 30 条，导出 JSONL python run.py --hot-board 30 -p ./Downloaded # 关键词搜索"猫咪"，最多 100 条，导出 JSONL python run.py --search "猫咪" --search-max 100 -p ./Downloaded结果分别落在Downloaded/hot_board/和Downloaded/search/下，每条含标题、热度等元数据，可直接进 pandas 处理。
更进阶的做法是开启comments.enabled采集评论，每个作品会额外生成*_comments.json，点赞数、评论内容、二级回复都在里面，适合做用户反馈分析。
避坑手册：五个高频问题一次讲清
问：只能抓到 20 条作品，翻页就没了？排查：这是翻页风控的典型表现。解决：确认browser_fallback.enabled: true且headless: false，浏览器弹窗出现后手动完成验证码，不要立即关闭窗口。
问：Cookie 失效，下载全部报错？排查：控制台会出现登录相关的错误日志。解决：重新执行python -m tools.cookie_fetcher --config config.yml扫码刷新，几秒即可恢复。
问：进度条刷屏，日志被淹没？排查：进度阶段默认会打印大量行。解决：配置里progress.quiet_logs: true即可静默进度日志，需要调试时再加--show-warnings或-v临时打开。
问：想重新下载某个作品，但它被跳过了？排查：程序通过"数据库记录 + 本地文件"双重检查判断是否已下载，只删数据库不删文件不会触发重下。解决：同时清理对应 aweme_id 的本地目录和数据库记录：
sqlite3 dy_downloader.db "DELETE FROM aweme WHERE aweme_id = '<aweme_id>';"（先删掉Downloaded/作者名/post/*_<aweme_id>/目录，再删数据库行。）
问：下载很慢怎么办？排查：默认并发 5、默认速率限制 2 请求/秒，慢通常是网络或线程数问题。解决：在配置里调thread: 8（视机器配置而定），或给proxy填上代理地址，如http://127.0.0.1:7890。
收尾：照着这份行动清单走完
- 克隆仓库：
git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader，进入目录 - 装依赖：
pip install -r requirements.txt，需要自动 Cookie 时再加装 Playwright - 配 Cookie：运行
python -m tools.cookie_fetcher --config config.yml扫码登录 - 跑最小用例：
python DouYinCommand.py或python run.py -c config.yml，先验证单视频下载 - 按需进阶：从"进阶闯关"和"实战演练"里挑一个场景配置抄进
config.yml - 定期维护：Cookie 失效就重跑抓取脚本，升级代码前备份
config.yml与数据库文件
最后提醒一句：工具本身开源免费，但请尊重原创内容版权，仅在个人学习、研究或合理使用范围内使用下载内容，并留意平台规则与接口策略的变更。
项目地址：https://gitcode.com/GitHub_Trending/do/douyin-downloader开源协议：MIT License适用平台：Windows / macOS / Linux依赖环境：Python 3.8+（另有可选依赖 Playwright、fastapi + uvicorn）
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
