douyin-downloader 使用指南：4 步完成抖音去水印批量下载
【免费下载链接】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 是一个面向抖音内容的开源批量下载工具，支持单条视频、图文作品、用户主页、主题合集、音乐原声与直播间去水印抓取，内置并发调度、SQLite 去重与增量下载机制，提供 Python 命令行版与 Douzy 桌面版两套入口，共用同一套下载后端。
四步跑通首次抖音批量下载
环境要求 Python 3.9+，支持 Windows、macOS、Linux。
第 1 步：克隆仓库并安装依赖
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第 2 步：获取并保存登录 Cookie
cp config.example.yml config.yml python -m tools.cookie_fetcher --config config.yml在弹出的浏览器中登录抖音，回到终端按 Enter，Cookie 自动写入config.yml。Cookie 共有三种配置方式：脚本自动获取；手动在配置中填写cookies键值对（msToken、ttwid、odin_tt、passport_csrf_token等）或粘贴整串 Cookie；用环境变量DOUYIN_COOKIE覆盖配置文件。优先级为命令行 > 环境变量 > 配置文件 > 默认值。
第 3 步：把示例链接换成目标链接
link: - https://www.douyin.com/user/YOUR_SEC_UID path: ./Downloaded/number.post控制下载条数，0表示不限，详见 config.example.yml。
第 4 步：运行下载
python run.py -c config.yml运行时可看到进度、并发数与成功/失败统计。完整参数用python run.py --help查看，-t调并发，-v输出详细日志，-u追加链接。
抖音去水印下载支持的内容类型全景
| 下载对象 | 典型 URL 格式 | 处理说明 |
|---|---|---|
| 单个视频 | /video/{aweme_id} | 解析作品 ID 后直接请求无水印源文件 |
| 图文作品 | /note/{note_id}（另识别/gallery/、/slides/） | 逐张下载图集媒体，与视频共用同一套命名与去重规则 |
| 用户主页 | /user/{sec_uid} | 翻页收集作品，按mode（post/like/mix 等）与number上限筛选 |
| 主题合集 | /collection/{mix_id}或/mix/{mix_id} | 展开合集中全部作品逐条下载，支持数量上限 |
| 音乐原声 | /music/{music_id} | 提取作品使用的原声音乐文件 |
| 直播间 | live.douyin.com/{room_id} | 实时录制直播流，可设最大时长、分块大小与空闲超时 |
命令行版以抖音为主；桌面版 Douzy 在同一套后端之上扩展了 TikTok、YouTube、Telegram、X 等平台，粘贴链接即可发起任务。
输入、处理、输出：抖音批量下载任务的数据流
输入段：工具读取config.yml与命令行参数，按"默认值 < 配置文件 < 环境变量（DOUYIN_COOKIE、DOUYIN_PATH、DOUYIN_THREAD、DOUYIN_PROXY）< 命令行"逐级合并。URL 解析器识别链接类型（video/note/user/collection/music/live），主页类任务先翻页收集作品 ID 列表，再按start_time/end_time（格式YYYY-MM-DD，含结束日当天）与number数量上限筛选，把任务清单收窄到真正需要处理的作品。
处理段：队列由thread控制的并发工作器消费，默认 5 并发；接口请求统一受rate_limit（默认 2 次/秒，附加随机抖动）约束，避免请求过于激进触发风控。每条作品走"请求接口 → 校验媒体信息 → 落盘文件"路径，失败时按 1 秒、2 秒、5 秒退避重试，默认最多重试 3 次（retry_times: 3）。去重发生在本段入口：先查磁盘是否存在非空主媒体文件，再查 SQLite 下载记录，两层都命中直接跳过，因此同一批链接重复运行只会补下新增或缺失的文件。
输出段：媒体文件按"作者/模式/文件"结构写入path目录，作者层默认用昵称（可切换为sec_uid或nickname_uid），文件名由filename_template渲染（默认{date}_{title}_{id}）。每条作品同时向download_manifest.jsonl追加一条 JSON 记录；database: true时作品明细写入 SQLite 库dy_downloader.db的aweme表，供历史查询与增量去重使用。
抖音下载故障场景与系统行为对照
| 故障场景 | 系统行为 |
|---|---|
| 单次请求失败、网络抖动 | 进入指数退避重试，等待节奏 1 秒、2 秒、5 秒，默认最多重试 3 次（retry_times: 3） |
| 单条作品持续失败 | 该条标记失败并跳过，队列继续消费后续任务，批次结束后统一输出失败汇总 |
| 视频已被删除或设为私密 | 判定为源不可用，自动跳过，不阻塞整批任务 |
| 主页作品列表分页受限 | browser_fallback.enabled: true（默认）时触发 Playwright 浏览器兜底采集作品 ID，再回接口补全详情；遇验证码页需headless: false人工完成验证 |
| 单视频、合集、音乐等接口被风控 | CLI 无法绕过，更新 Cookie 或反复重试均无效，建议改用 Douzy 桌面版 |
⚠️ 需要说明：README 已明确当前抖音接口风控会阻止 CLI 下载单条视频/图文、合集、音乐、喜欢与收藏，主页浏览器兜底不保证成功；直播录制属于实验功能，HLS 源仅保存播放列表而非可直接播放的视频。平台策略变化可能随时影响任意功能可用性。
抖音批量下载关键配置项速查
| 配置项 | 说明 | 取值示例 |
|---|---|---|
filename_template/folder_template | 命名模板，可用变量{id}、{title}、{author}、{date}、{year}、{mode}等，保留{id}可避免重名覆盖 | {date}_{title}_{id}（默认） |
start_time/end_time | 按作品发布时间过滤，含结束日当天 | 2026-01-01/2026-06-30 |
number.post | 各模式下载数量上限 | 0（不限）或10 |
thread | 并发下载线程数 | 5（默认），可上调 |
video_quality | 画质档位；original探测上传原片，探测失败自动回退最高转码档 | highest（默认）/original/1080p |
increase+redownload_missing_files | 增量下载总开关；主媒体文件缺失时是否补下 | increase.post: true |
database | 是否写入 SQLite 下载历史库 | true（默认） |
proxy | 接口请求与下载走代理 | http://127.0.0.1:7890 |
live.max_duration_seconds | 直播录制最大时长，0表示录到主播下播 | 0 |
notifications.enabled | 完成通知，providers 支持 bark / telegram / webhook | false（默认） |
完整字段与默认值见 config/default_config.py，命名变量的渲染与清理逻辑见 utils/naming.py。
三个真实用法组合
定时增量收集：把start_time设为最近 7 天，保持各模式increase: true与database: true，用 cron 按周执行python run.py -c config.yml，二次运行只补新增作品；同时开启notifications并配置 Bark 或 Telegram，任务结束自动推送到手机，夜间挂机跑批无需守在终端前。
竞品监控与素材归档：mode: [post]+number.post限定条数 +json: true归档作品元数据，author_dir: nickname_uid防止作者改名导致目录分裂；排障时加-v查看详细日志，定位卡在接口阶段还是传输阶段。
免配置日常使用：日常抓取用 Douzy 桌面版，左侧边栏管理账号与订阅，任务中心跟踪每条批量任务状态，粘贴链接、勾选内容类型即可发起任务，无需接触配置文件；TikTok、YouTube 等平台的链接任务也走同一套后端。
需要把下载能力挂到自有系统时，可启动可选的 REST API 服务模式：python run.py --serve --serve-port 8000（需额外安装 fastapi 与 uvicorn，job 记录默认保留 24 小时）。
抖音去水印下载高频问题解答
提示 Cookie 失效或需要登录，怎么办？重新运行python -m tools.cookie_fetcher --config config.yml，浏览器里完成登录后按 Enter 覆盖保存即可。注意更新 Cookie 不能解决接口风控本身造成的限制。
主页只获取到少量作品？保持browser_fallback.enabled: true且headless: false，程序检测到验证码页会等待你在浏览器中人工验证，验证后自动继续采集；风控严重时仍可能受限。
个别视频持续失败是什么原因？大概率是源作品已被作者删除或设为私密，属于源头不可用，系统自动跳过并继续后续任务，不影响整批结果。
文件名混乱甚至互相覆盖？检查filename_template是否包含{id}变量，这是保证唯一性的关键字段；缺失值会被渲染为空串，模板过短或缺少{id}时容易同名。
二次运行会不会重复下载？保持database: true且各模式increase为true，SQLite 记录加磁盘文件校验的双重去重只会处理新出现的作品。需要强制重下时，把对应模式的increase设为false，无需清空数据库。
下载速度不达预期，如何排查？先上调thread观察吞吐变化；再检查网络环境，必要时填写proxy走代理；用-v输出详细日志，确认瓶颈在接口请求还是文件传输阶段。
适用人群与使用合规
这套工具适合三类人：需要周期性收集作者内容的素材整理者（定时任务 +increase增量下载 +notifications推送）；做竞品监控的运营人员（主页批量抓取 +json: true元数据归档 + 时间区间过滤）；希望免配置直接使用的普通用户（Douzy 桌面版，粘贴链接即完成一次抖音合集批量下载）。
它不适合以破解付费内容为目的的场景，也不适合要求 100% 稳定绕过平台风控的用途，接口策略变化随时会影响可用性。请在合法合规的个人数据管理场景下使用本工具，尊重原创者的版权与劳动成果，遵守平台规则与隐私要求，并自行承担使用责任。
准备好环境后，先完成克隆仓库、保存第一个 Cookie、填入一条目标链接这三件事，一个完整的抖音去水印批量下载流程在半小时内即可跑通。
【免费下载链接】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），仅供参考
