抖音下载器上手指南：从 Clone 到批量下载无水印作品只需 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 是一个用 Python 编写的抖音批量下载工具，核心能力是下载抖音无水印视频、图文，并支持按博主主页批量采集、日期筛选、失败重试、增量去重，以及可选的评论采集、视频转写和完成通知。它的定位是"实用"而非"大而全"：命令行版专注抖音，日常交互则交给配套桌面版 Douzy。

这个项目有两种使用方式，先分清再选：

• Douzy 桌面版：日常使用首选，粘贴链接即可下载，带任务中心、作品档案等图形化面板，除抖音外还支持 TikTok、YouTube、Telegram、X。
• Python 命令行版：脚本集成首选，YAML 配置驱动，适合批量任务、定时任务和二次开发。

需要注意一个现实限制：自 2026 年 8 月起，抖音接口风控陆续覆盖了作品详情、合集、音乐、喜欢、收藏等接口，CLI 目前能稳定走通的主要是博主主页作品的批量下载（可借助 Playwright 浏览器兜底，但不保证成功）。日常下载单个视频、合集等内容，官方建议直接使用 Douzy。

Douzy 桌面版界面一览

抖音平台的主任务配置页：勾选作品、喜欢、合集、音乐等下载模式，并设置数量上限与筛选条件

其他平台走统一的链接任务流程：粘贴链接、检测、提交

YouTube 工作台支持频道、播放列表与 Shorts 的扫描式处理

🚀 快速上手：从 Clone 到第一次下载

环境要求不高：Python 3.9+，Windows、macOS、Linux 均可。安装分两步，基础依赖加浏览器自动化支持（Cookie 抓取和浏览器兜底都需要 Chromium）：

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 # 下载 Chromium 内核

接下来配置 Cookie。把示例配置复制为config.yml，运行抓取工具：

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

命令会弹出一个浏览器窗口，你在里面登录一次抖音，回到终端按 Enter，Cookie 就写入配置了。之后只需把link换成目标博主的主页链接，加上数量限制，即可跑通最小流程：

link: - https://www.douyin.com/user/你的sec_uid path: ./Downloaded/ mode: [post] number: post: 10 # 最多下载 10 条，0 表示不限 increase: post: true # 跳过已下载作品

python run.py -c config.yml

运行后终端会用 rich 渲染实时进度，完成后在./Downloaded/下得到按作者分目录的作品文件。全部命令行参数可用python run.py --help查看，最常用的几个：

🧩 模块分层：谁负责什么

这个抖音下载器的代码组织很清晰，七个子目录各司其职，看目录名就能猜到职责：

douyin-downloader/ ├── run.py # 入口，转交给 cli.main ├── cli/ # 参数解析、异步主循环、进度展示 ├── config/ # YAML 配置加载、环境变量覆盖、默认值 ├── core/ # URL 解析、API 客户端、各类下载器 ├── auth/ # Cookie 与 MS token 管理 ├── control/ # 限速、重试、并发队列 ├── storage/ # SQLite 历史库、文件管理、元数据 ├── tools/ # 浏览器 Cookie 抓取等独立工具 └── utils/ # 日志、文件名清洗、反爬签名

几条值得知道的实现细节：

• 配置优先级是命令行 > 环境变量 > 配置文件 > 默认值，环境变量用DOUYIN_*前缀，方便在 CI 里覆盖。
• core/里用工厂模式把 URL 类型映射到具体下载器：/video/、/note/、/user/、合集、音乐等链接各自路由到对应实现，全部继承同一个BaseDownloader。
• 用户主页的多种下载模式（post / like / mix / music / collect）以策略模式放在core/user_modes/，注册表自动发现，加新模式不用改主流程。
• 全部 I/O 是异步的（aiohttp + aiosqlite + aiofiles），限速、重试、队列集中在control/，下载逻辑本身保持干净。

⚙️ 核心能力拆解

增量下载：磁盘文件说了算

批量采集最怕的是重复下载。这个工具的去重逻辑是：先查磁盘上该作品的非空主媒体文件是否存在，存在就跳过。increase.post控制每个模式是否启用增量，设为false会强制重下并覆盖当前筛选范围内的文件——不需要清空数据库。另一个开关redownload_missing_files（默认true）决定文件缺失时是否补下。SQLite 库只记录下载历史（aweme明细表 +download_history任务表），不参与跳过判断，所以关掉database也不影响去重。

并发、限速与重试

批量任务默认 5 个并发线程（thread），每次 API 请求间隔由rate_limit（默认 2 次/秒）约束，失败自动重试retry_times（默认 3 次）。这套组合的目的是在保证速度的同时尽量不触发频率限制，网络不稳时可以把retry_times调到 5。

浏览器兜底：翻页被限时的 Plan B

当 API 翻页被风控卡住（比如只返回 20 条）时，可以启用browser_fallback：用 Playwright 驱动真实浏览器加载主页，滚动采集作品 ID 再补全详情。headless: false时窗口可见，方便你手动过验证码。要提前管理预期：这是"尝试"而非保证，风控收紧时可能同样拿不到数据。

无水印与附带产物

下载默认只保存视频本体；封面、音乐、头像、原始 JSON 都是可选开关（cover/music/avatar/json），默认关闭。图文会优先选用无水印字段，取不到才回退到带水印地址。

📝 关键配置详解

以下是最常用的配置项（完整带注释的配置见 config.example.yml）：

命令行参数会覆盖配置文件，所以"配置文件设默认、命令行做一次性调整"是比较顺手的用法。

🗂️ 输出目录结构与命名模板

默认（folderstyle: true）落盘结构是三层：作者 → 模式 → 单个作品：

Downloaded/ ├── download_manifest.jsonl # 每行一条作品的下载清单 ├── dy_downloader.db # SQLite 历史库 └── 作者名/ ├── post/ │ └── 2024-02-07_作品标题_aweme_id/ │ ├── 2024-02-07_作品标题_aweme_id.mp4 │ ├── 2024-02-07_作品标题_aweme_id_cover.jpg # 开启 cover 后 │ ├── 2024-02-07_作品标题_aweme_id_music.mp3 # 开启 music 后 │ └── 2024-02-07_作品标题_aweme_id_data.json # 开启 json 后 ├── like/ ├── mix/ └── music/

命名由两个模板控制，默认都是{date}_{title}_{id}。可用变量 15 个：{id}{title}{author}{author_id}{date}{year}{month}{day}{time}{hour}{minute}{second}{timestamp}{type}{mode}。日期取作品发布时间create_time，缺失时回退当天并记录告警。

两个容易踩的坑：

• 模板里去掉{id}虽然允许，但基于文件名的判重会失效，默认配置下重跑会重复下载。
• author_dir控制作者目录命名：nickname（默认，直观但重名会合并）、sec_uid（唯一但不直观）、nickname_uid（兼顾，重度用户推荐）。切换只影响后续下载，不会迁移旧目录。

🛠️ 典型工作流

当你要长期跟踪一个博主

把number.post设为0、increase.post保持true，定期重跑同一条命令即可只补新作品。想存档更全，可打开author_url: true和homepage_screenshot: true，在作者根目录各存一份主页地址文本和首屏截图：

number: post: 0 # 不限数量 increase: post: true # 增量：只下新作品 author_url: true

当你只需要某个时间段的内容

用start_time/end_time圈定范围（格式YYYY-MM-DD，含结束日），比如只收集 2025 年的作品：

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

当你做趋势分析而不是囤视频

两条命令直接导出结构化数据为 JSONL，不需要下载媒体文件：

python run.py --hot-board 30 # 热搜榜前 30 名 python run.py --search "关键词" --search-max 50

📡 把下载器变成 REST 服务

如果要把这个抖音下载器接入自己的系统，它内置了一个轻量的 FastAPI 服务模式，fastapi和uvicorn是可选依赖：

python -m pip install fastapi uvicorn python run.py --serve --serve-port 8000

服务复用同一套配置和 Cookie，接口很薄：

任务在内存中保留server.max_jobs（默认 500）条，完成态保留job_ttl_seconds（默认 24 小时）。并发数同样受thread约束。

🩹 常见问题速查

另外提醒：Cookie 建议每月至少更新一次；下载内容请仅用于个人学习、个人数据管理，遵守平台规则与版权要求。

✅ 总结

douyin-downloader 把"批量下载抖音无水印作品"这件事做成了可脚本化的流程：YAML 配置 + 增量去重 + 并发限速重试，外加评论采集、转写、通知、REST 服务这些按需开启的扩展能力。架构上分层清晰，core/的下载器和control/的调度是解耦的，想扩展新下载模式或新通知渠道都有现成的模式可以套。

建议先用默认配置跑通一次最小流程：cookie_fetcher登录、number.post限制到 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