企业官网建设流程全解析

抖音下载实战指南：5 个关键配置让平台限频下依然稳定取内容

【免费下载链接】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 用模拟真实浏览器行为来应对：自动读取登录态、把请求节奏压到人速、失败自动补刀。这篇指南带你 10 分钟内跑通首个下载，之后可以放心批量抓整个主页。

🧰 能力速览

• 无水印下载：自动选无水印源，覆盖单条视频、图集、合集、音乐
• 登录态自动获取：拉起浏览器扫码，回车即把 Cookie 存进配置
• 限速 + 重试双保险：默认 2 次/秒，失败按 1s→2s→5s 递增等待补发
• 浏览器兜底：翻页被拦时自动打开浏览器，验证码可人工介入
• 增量去重：磁盘加 SQLite 双重记录，二次运行直接跳过已下载
• 进度可见：实时进度条，支持静默模式和完成通知推送

⚡ 快速上手

环境三步搞定：装依赖、拿登录态、跑通一个视频。

第一步，装好运行环境：

# 克隆仓库并安装核心依赖（需 Python 3.8+） git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader pip install -r requirements.txt # 可选但强烈建议：装浏览器内核，Cookie 自动获取和验证码兜底都靠它 pip install playwright && python -m playwright install chromium

第二步，获取登录态：

# 复制一份默认配置 cp config.example.yml config.yml # 启动自动获取工具，会弹出浏览器窗口 python -m tools.cookie_fetcher --config config.yml # 在窗口里扫码登录，回到终端按 Enter，Cookie 自动写回 config.yml

第三步，跑通首个下载：

# 单条视频链接试水，文件默认落在 ./Downloaded/ python run.py -u "https://www.douyin.com/video/xxxxxx" -c config.yml

同一套后端还提供桌面版（Douzy），粘贴链接即下，命令行流程与本文一致

📦 核心功能拆解

登录态搞定后先别急着批量跑，下面 5 个机制各管一块，看懂了再调参数不慌。

如何自动获取并保住有效登录态

适用场景：第一次使用，或下载时报"需登录"、接口返回空，先做这一步。

怎么实现：

• tools/cookie_fetcher.py 用 Playwright 拉起一个真浏览器，由你手动扫码完成登录
• 工具监听页面请求，同时抓取 Cookie 头里和地址栏参数里的 msToken（平台用来识别网页访客的令牌）
• 只回写 msToken、ttwid、odin_tt、passport_csrf_token 这几个必要项，附带 sid_guard 等登录凭证，不塞无关字段
• 结果落到 config.yml 的 cookies 段，之后所有请求直接复用，无需重复登录

关键参数：缺任何一个必需键工具都会明确提示，不会静默存一份废配置；不想动配置文件时可单独导出到config/cookies.json。

如何把请求频率调到不触发风控

适用场景：整站批量前确认节奏合适。默认值已经按"真人刷手机"设计，多数情况不用动。

怎么实现：

• 全局限速器保证两次请求之间至少间隔 1/max_per_second 秒
• 每次放行后再随机多等 0~0.5 秒（抖动），避免"节拍器式"固定间隔被识别
• 并发任务通过同一把锁排队取号，线程再多也不会冲破速率上限
• 单次请求失败不硬刚，交给重试模块按递增等待补发

关键参数：rate_limit默认 2（每秒 2 个请求），与thread默认 5 路并发配套；频繁被拦就把rate_limit降到 1。实现见 control/rate_limiter.py。

如何命中验证码时自动兜底

适用场景：抓博主主页翻页中途被平台拦下（弹验证码或返回空），不用手动重启。

怎么实现：

• 检测到 API 翻页受阻后，自动拉起本地浏览器，模拟滚动加载继续取数
• 默认非无头模式，窗口留在前台，出现验证码时你可以直接人工点掉
• 滚动达到上限、或连续若干轮没有新内容时自动收手，不无限空转
• post模式已完整验证，like/mix 等模式目前主要依赖 API 翻页

关键参数：browser_fallback.enabled默认 true，max_scrolls上限 240 轮，wait_timeout_seconds600 秒（留给你人工处理验证码的时间）。

如何降低批量下载的失败率

适用场景：网络不稳时批量总有个别条目超时、半截文件，靠这组机制自动救回。

怎么实现：

• 请求失败后按 1 秒→2 秒→5 秒递增等待再发，不是一失败就立刻重锤
• 默认 5 路并发，单条失败不中断整批，进度条照常推进
• 文件下完后拿实际大小和服务端声明的 Content-Length 对账，不符就删掉重新下
• 每条下载元数据写入 SQLite（默认dy_downloader.db），方便复盘和增量判断

关键参数：retry_times默认 3（首次之外最多补 3 次），thread默认 5，弱网环境降到 3 反而更稳。重试逻辑在 control/retry_handler.py。

桌面版任务中心思路一致：任务互相隔离，失败项可以单独重跑

如何避免重复下载旧内容

适用场景：想定期同步某几个博主的新更新，又不想把三个月前的视频再存一遍。

怎么实现：

• 每种模式有独立增量开关（increase.post等），开启后跳过已判定下载过的条目
• 判断先看磁盘主文件；文件被删时默认重新下载，也可改为信数据库记录
• mode支持 post（发布）、like（喜欢）、mix（合集）、music（音乐）、collect/collectmix（收藏夹）六种
• 用户模式各自是独立策略实现，想看某模式行为可直接读对应策略文件

关键参数：number.post设为 0 表示抓全量；配合start_time/end_time可只取指定时间段的作品。

桌面版可按博主同步内容并筛选新作品，与命令行增量下载目标一致

📋 参数速查

🩺 常见问题排查

Q：下着单条视频突然报"需登录"或返回空，怎么办？A：登录态过期了，重新跑一遍python -m tools.cookie_fetcher --config config.yml刷新即可。

Q：Cookie 刚拿的，过几天就失效，是不是坏了？A：这是正常现象，网页登录态本身有有效期。大批量任务开跑前重新抓一次，耗时不到一分钟。

Q：网络不稳时磁盘上留下半截视频，要手动清吗？A：不用。程序下载完会和服务端声明的长度对账，不符自动删除并走重试流程。

Q：翻页卡验证码，是不是每次都得手动点？A：browser_fallback默认开启，命中后会自己拉起浏览器，你在窗口里点一次验证码即可，后续抓取继续在该浏览器里进行，post 模式支持最好。

Q：第二次运行把同样的视频又下了一遍？A：先确认increase.*是 true。磁盘文件被手动删掉时，默认行为就是重下（redownload_missing_files为 true）；改成 false 可在数据库仍有记录时直接跳过。

⚖️ 合规提醒

• 仅用于个人学习与备份，尊重创作者版权，下载内容请勿二次分发
• 控制请求频率，不要对单一账号做长时间不间断抓取
• 平台规则随时可能调整，若账号被限频，降速或改到低峰时段再跑
• 本工具不提供绕过付费内容、私密内容访问的能力

📚 延伸阅读

• Playwright 官方文档：浏览器兜底与 Cookie 自动获取的底层技术，浏览器搜 "Playwright Python" 即可找到
• 完整功能清单与已知限制：README.zh-CN.md 的 "Current Limitations" 一节
• 源码入口：用户模式策略在 core/user_modes/，全部可配参数及注释见 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