抖音下载器 douyin-downloader 完整指南：从去水印单条到整站主页批量归档
项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader 你盯上一个持续更新的美食博主，想把他 200 条视频按发布时间完整存下来？录屏存不了音画完整的一条，手动点下载更是没完没了。douyin-downloader 就是为此设计的抖音批量下载工具：粘贴链接，无水印、按原画质抓完视频、图集、合集和音乐，还带进度条、失败重试和数据库去重。
它的价值可以压缩成三条：
- 无水印 + 画质自选：自动挑无水印源，默认取最高转码档，也能指定"原画"探测上传原片
- 主页批量 + 增量：
post/like/mix/music四种模式，increase打开后每次只下新作品 - 不白干：SQLite 记录 + 本地文件双重去重，网络断了重跑不会重复下载
五步跑通第一次下载
先装环境。需要 Python 3.8+，macOS、Linux、Windows 都能跑：
git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader
cd douyin-downloader
pip install -r requirements.txt
浏览器兜底是重要能力（翻页被风控时会启动真实浏览器），建议顺手装上：
pip install playwright
python -m playwright install chromium
接下来四步：
cp config.example.yml config.yml，把要下载的链接填进link列表- 运行
python -m tools.cookie_fetcher --config config.yml，会弹出浏览器让你扫码登录抖音，回终端按 Enter，Cookie 自动写回配置 - 在
config.yml里确认mode（想下作品就填post）和path（保存目录，默认./Downloaded/） - 运行
python run.py -c config.yml，终端里看到进度条走到 100% 就成功了
按"你要解决的问题"拆能力
"我想存一条视频，顺便留档"
把 /video/{aweme_id} 或 v.douyin.com 短链放进 link 就行，短链会自动解析成真实地址。除了 mp4 本体，config.yml 里还有 cover、music、json、avatar 四个独立开关，打开 json: true 后每条作品会附带一个 _data.json，里面是发布时间、点赞数等结构化元数据——做分析的人用得上。
"我要把整个账号存档，还要按时间筛"
链接换成 /user/{sec_uid} 主页地址，mode 里加 post。两个参数决定量：number.post 控制条数（0 表示全量），start_time / end_time 控制时间窗（格式 YYYY-MM-DD）。比如只留 2024 年的内容，设 start_time: "2024-01-01" 和 end_time: "2024-12-31" 即可，翻页时超出窗口会自动停止。
"我关注了一批账号，每天只想要新作品"
这是增量模式的用武之地：increase.post 设 true，配合 database: true，数据库会记住已下过的每条作品，重跑只拉新增。多账号就塞多条 link，跨模式（post/like/mix 混用）也会按 aweme_id 自动去重，同一条视频出现三次也只下一次。
"我下完的几百个文件想管理起来"
默认 folderstyle: true，每条作品一个独立目录，命名走 {date}_{title}_{id} 模板，外面再套一层作者名目录。整批下载结束还会在 Downloaded/ 根下生成 download_manifest.jsonl 总清单。想要可视化，同一套后端有桌面版 Douzy：关注列表同步、任务中心里看成功/失败条数、一键重试失败项，都在本地跑。
"视频下完还想要别的"
按需打开就行：comments.enabled: true 给每条作品抓评论存成 _comments.json（可含二级回复）；live 相关配置支持把 live.douyin.com 直播间录成 FLV，主播下播或你 Ctrl+C 时已录的字节都会保留；transcript.enabled: true 则把视频音频转写成 txt/json 文稿，需要配置 OpenAI 密钥。
原理速览：它凭什么稳
- 限速 + 退避重试：默认 2 请求/秒的速率限制，失败按 1s→2s→5s 指数退避重试（默认 3 次），不是无脑狂刷接口，被限流概率低很多。
- 双重去重：SQLite 数据库记下载历史，同时扫描本地文件名里的 aweme_id。数据库和文件"双保险"，意味着你删了文件但库还在，程序仍知道下过；只删文件则会触发重下——这个行为要心里有数。
- 浏览器兜底：API 翻页被风控截断时，自动起 Playwright 浏览器，读页面自己发出的请求继续翻页，弹出验证码时你手动过一下就行。相关逻辑在 core/ 和 control/ 目录里。
- 策略模式模块化：每种下载类型（视频、图集、合集、音乐、用户主页各模式）是独立下载器，由 core/downloader_factory.py 统一分发，用户主页的 post/like/mix 等策略在 core/user_modes/ 里各占一个文件——改一处不牵连全局，这也是 tests/ 里能堆到 70+ 测试文件的原因。
三个人的真实用法
剪辑师阿泽：备份参考素材
- 需求：盯 3 个教程类账号，每周有新视频就归档，别下重复的
- 做法：
config.yml里填 3 条主页链接，mode: [post]、increase.post: true、database: true，写个脚本每天定时跑一次python run.py -c config.yml - 结果：一周累计新增 11 条，全部落在各自作者目录下，重复的 0 条
数据运营小赵：竞品内容分析
- 需求：拉一个账号 2025 年全年的作品 + 元数据，不进剪辑流程只要数据
- 做法：
start_time/end_time框定 2025，json: true，把video关掉（只要封面和 JSON 的话再按需留） - 结果：拿到 180 条
_data.json，发布时间、点赞、评论数直接能进 pandas 做分布图
自媒体的大刘：抢救自己账号
- 需求：准备换手机号，先把旧账号 400 条作品全量备份
- 做法：主页链接 +
number.post: 0（不限数量），cover/music/json全开，thread: 8拉高并发 - 结果：约 40 分钟跑完 400 条，中途 2 条失败，重跑一次由重试机制自动补齐
踩坑速查（按你最容易先碰到的顺序排）
只抓到 20 条左右就停了 原因：翻页触发风控，API 通道被截断。解法：确认 browser_fallback.enabled: true 且 headless: false，浏览器弹窗出现后手动过完验证码，别急着关窗。
Cookie 突然全部失效 现象是请求批量 401/403。抖音 Cookie 有效期很短，过期是常态不是异常。重跑一次 python -m tools.cookie_fetcher --config config.yml 扫码即可，建议把这条命令记成"每周固定动作"。
明明删了文件，重跑却说已下载 原因是去重是"数据库 + 文件"双重判断，库里还有记录就跳过。要真正重下，得把 dy_downloader.db 里的对应记录一并删掉；反过来只删文件不删库，程序会因为"库里有、文件没有"而重新下载。
进度条疯狂刷屏日志 默认已开 progress.quiet_logs: true 静默处理。如果你手动关了它想排查问题，记得调试完再改回去，否则批量任务会把终端刷到卡。
老用户的四个进阶开关
- 并发调优：
thread默认 5，稳一点的网络可以提到 8-10；同时留意retry_times，并发越高瞬时失败越多，两者要一起看 - 画质分层：
video_quality除了默认的highest，还能设original（探测上传原片，可能比转码档大数倍，代价是每条多一次 10 秒探测）或指定1080p/720p省空间 - 目录结构：作者重名或常改名的，把
author_dir从nickname换成nickname_uid，直观且不会串目录 - 无人值守：
notifications里接 Bark/Telegram/Webhook，批量任务跑完直接推手机，配合系统定时任务就是完整的日更归档流水线
边界与合规
只下载公开内容，不碰私密和付费内容；素材商用前先确认版权。Cookie 等于账号钥匙，建议用专门账号登录获取，别拿主力账号试。另外注意：抖音风控在 2026 年持续升级，部分接口对 CLI 直连已限制，遇到功能受限先看 README 的限制说明，浏览器兜底或桌面版是当前最稳的绕过路径。
现在可以做的四件事
- 先拿一条自己熟悉的视频链接跑通全流程，熟悉配置里每个开关的位置
- 把
json: true打开——元数据是你后续筛选、去重、分析的全部本钱 - 批量任务配好
increase+database，让重跑变成"补漏"而不是"重来" - 遇到风控截断别硬刷，装上 Playwright 走浏览器兜底
工具替你干的是重复劳动，判断哪些内容值得存、存下来怎么用，仍然是你的事。
参考文档：docs/ · 核心逻辑：core/ · 配置加载：config/config_loader.py
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
