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（asyncio+aiohttp）编写的抖音批量下载工具，覆盖单条链接与作者主页两级范围的无水印下载：视频、图文图集、合集与音乐原声，并内置并发限速、指数退避重试和 SQLite 去重。一切由一份 YAML 配置加一条python run.py -c config.yml命令驱动。硬性前提是有效的抖音 Cookie 登录态（由 tools/cookie_fetcher.py 获取），且自 2026-08 起平台风控已封锁大部分 API 直连路径，能力边界必须先看清再动手。

先看清单：支持什么、被风控挡住什么、前提是什么

适合两类人：需要按作者归档抖音作品库的开发者，以及要做本地内容备份的管理者。它解决的是"多链接、去重、可重复执行"的批量问题，而不是单次下载。

• 可用：作者主页作品下载（当前唯一走得通的 API 外围路径是浏览器兜底）、直播录制（实验性）、热搜榜与关键词搜索的 JSONL 导出（--hot-board/--search）、REST API 服务模式（--serve，需fastapi+uvicorn）。
• 被 403 拦截（2026-08 起）：单条视频/图文、合集、音乐、点赞列表、收藏夹的 CLI 直连接口均被 ArgusSecurityPlugin 拒绝，刷新 Cookie 无法修复；主页作品仅能走 Playwright 浏览器兜底，且官方声明不保证成功。
• 明确不支持：抖音放映厅影视内容（lvdetail，DRM 加密无成片可取）；HLS 直播源只保存 playlist 文件而非可播放视频，需 ffmpeg 后处理。
• 前提条件：有效 Cookie（msToken、ttwid、odin_tt、passport_csrf_token等键）；浏览器兜底与取 Cookie 都依赖playwright+ chromium；ffmpeg、OpenAI 密钥、fastapi/uvicorn均为可选依赖。

第一次运行：5 步完成安装、登录与首次下载

1. 克隆仓库并安装核心依赖（要求 Python 3.9+，Windows/macOS/Linux 均可）：

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

2. 安装浏览器组件。取 Cookie 和翻页兜底共用这一套，缺一不可：

python -m pip install playwright python -m playwright install chromium

3. 复制配置并完成 Cookie 登录。命令会打开浏览器进入抖音，手动登录后回到终端按回车，Cookie 自动写入config.yml：

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

4. 写最小配置。示例里number.post: 1只抓 1 条，首次验证建议改成小整数，确认无误再放开为0（不限）：

link: - https://www.douyin.com/user/YOUR_SEC_UID path: ./Downloaded/ mode: - post number: post: 10

5. 执行第一条下载命令。临时追加链接不改配置用可重复的-u参数；--help可查看全部选项（-p改目录、-t改并发等）：

python run.py -c config.yml

配置速查：10 个最常改的参数及其默认值

场景走查：一次作者主页增量下载 + 一次自己的收藏夹

场景 A：下载某作者指定时间段的全部作品（6 步）

1. 在 config.example.yml 基础上把link填为主页地址，start_time/end_time限定区间，number.post: 0表示全量。
2. 执行python run.py -c config.yml；cli/main.py 校验配置、按需初始化 SQLite，再逐条遍历链接。
3. 短链先由 core/api_client.py 重定向解析，core/url_parser.py 从 URL 中提取sec_uid并输出链接类型。
4. core/downloader_factory.py 把user类型分发给 core/user_downloader.py，按mode执行 core/user_modes/ 下的策略；post策略按游标翻页，作品发布时间越过时间上界即提前停止（core/user_modes/post_time_boundary.py）。
5. 每条作品进入 core/video_downloader.py 挑选无水印源、按video_quality选档；thread（默认 5）个 worker 并发拉流，单请求限速 2 次/秒（control/rate_limiter.py），失败重试 3 次、退避 1s/2s/5s（control/retry_handler.py）。
6. API 翻页被拒时由 core/api_client.py 启动浏览器兜底：读取页面自己发出的作品列表请求，最多等 600 秒人工过验证；文件经 storage/file_manager.py 落盘，storage/database.py 用aweme表记录 + 文件名中的aweme_id双重去重。

场景 B：下载自己的收藏夹（4 步）

1. mode设为[collect]（收藏文件夹）或collectmix（收藏合集），link指向自己主页；这两者与post/like/mix/music不可混用，core/user_downloader.py 在_validate_mode_scope中直接拦截。
2. 收藏夹仅对当前 Cookie 对应的账号生效，列表由 core/api_client.py 拉取。
3. 现实约束：2026-08 起收藏夹接口的非浏览器请求被 403，CLI 没有签名通道，此场景大概率整体不可用，跑之前要有预期。
4. 能通过的部分，下载、命名与去重路径与场景 A 第 6 步完全一致。

六个常见现象的排查路径

1. 现象：主页任务最终只抓到前几十条甚至失败。原因：API 翻页被风控拒绝，浏览器兜底是唯一路径且官方不保证成功。处理：确认browser_fallback.enabled: true、headless: false，在 600 秒窗口内手动完成验证；仍无果属于平台现状，不是配置问题。
2. 现象：单条视频/点赞/收藏/合集/音乐接口返回 403Blocked by ArgusSecurityPlugin。原因：平台边缘风控拦截非浏览器请求，与 Cookie 新旧无关。处理：不要再反复刷 Cookie，这类内容当前只有同后端桌面版可用。
3. 现象：想重下某作品却被跳过。原因：去重是数据库记录 + 文件名aweme_id双重判断，只删了其中一份仍算"已下载"。处理：同时删除Downloaded/{作者}/{模式}/*_{aweme_id}/目录与aweme表对应记录。
4. 现象：增量模式仍重复下载旧作品。原因：database: false或对应模式increase为false。处理：置database: true、increase: true；反过来想强制重下并覆盖，就把increase置false。
5. 现象：速度慢、重试日志频繁。原因：并发过高或 IP 被限流。处理：调低thread、配置proxy走代理；单请求 2 次/秒的限速与 1s/2s/5s 退避是内置行为，属正常现象。
6. 现象：任务中途提示登录态失效。原因：Cookie 过期。处理：交互环境下工具会自动开浏览器重登一次并重跑当前链接；非交互环境手动重跑python -m tools.cookie_fetcher --config config.yml。

合规边界：开始下载前自问五条

• 下载内容仅限个人学习、研究与本地归档，不做二次分发或商业用途。
• 遵守抖音平台条款与所在司法辖区法规，不批量采集特定账号的私密数据，不侵犯创作者版权。
• 平台接口与风控策略随时调整会导致功能降级（本工具已先后经历 2026-08、2026-09 两轮封锁），这是需要接受的正常技术风险。
• CLI 为非浏览器直连，高频高并发会增加限流与账号风险，用thread与proxy自行控制节奏。
• 使用行为与后果由使用者自行承担。

工具适合需要搭建本地抖音内容归档库的开发者与内容管理者，完整参数清单与默认值见 config.example.yml。

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