抖音下载器 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 项目官方中文文档为核心系统讲解这套面向实用场景的抖音下载工具从单个视频、图文、合集、音乐下载到作者主页 post/like/mix/music 多模式批量下载、收藏夹同步、直播录制、评论采集、热搜与关键词搜索、REST API 服务化部署以及 SQLite 去重、浏览器兜底、完整性校验等可靠性机制。读完本文你将掌握完整的配置方法、全部命令行参数、典型场景配置模板并能结合源码理解每个参数背后的实现原理。一、项目定位与核心能力总览Douyin Downloader V2.0 是一个面向实用场景的抖音下载工具支持视频、图文、合集、音乐、收藏夹等多种类型下载以及作者主页批量下载。默认内置进度展示、失败重试、SQLite 数据库去重、下载完整性校验和浏览器兜底能力。项目同时提供基于同一套后端打造的桌面客户端 Douzy内测中为抖音、TikTok、YouTube 提供独立工作台支持多链接队列、任务状态跟踪、本地下载档案与快速重新下载。已支持功能功能说明单个视频下载/video/{aweme_id}单个图文下载/note/{note_id}、/gallery/{note_id}单个合集下载/collection/{mix_id}、/mix/{mix_id}单个音乐下载/music/{music_id}优先原声文件缺失时回退到该音乐下首条作品短链自动解析https://v.douyin.com/...、v.iesdouyin.com含裸 host用户主页批量下载/user/{sec_uid}mode: [post, like, mix, music]当前登录账号收藏夹下载/user/self?showTabfavorite_collectionmode: [collect, collectmix]无水印优先自动选择无水印视频源最高清自动挑选基于video.bit_rate数组自动选最高码率视频 实况图生效直播录制live.douyin.com/{room_id}→ FLV/HLS主播下播时保留已录数据评论采集按作品抓评论可含二级回复输出*_comments.json热搜榜 关键词搜索--hot-board [N]/--search 关键词结果落 JSONLREST API 服务模式--serve --serve-port 8000可选fastapi uvicorn完成通知推送下载完成后推 Bark / Telegram / Webhook附加资源下载封面、音乐、头像、JSON 元数据视频转写可选功能调用 OpenAI Transcriptions API并发下载可配置并发数默认 5失败重试指数退避重试1s, 2s, 5s速率限制默认 2 请求/秒SQLite 去重数据库 本地文件双重去重增量下载increase.post/like/mix/music时间过滤start_time/end_time浏览器兜底翻页受限时启动浏览器支持人工过验证码下载完整性校验Content-Length 比对不完整文件自动清理并重试进度条展示Rich 进度条支持progress.quiet_logs静默模式Docker 部署提供 DockerfileCI/CDGitHub Actions 自动测试和 lint当前限制说明浏览器兜底当前仅针对post完整验证like/mix/music主要依赖 API 正常分页。number.allmix/increase.allmix作为兼容别名保留运行时会归一化到mix具体见下文配置加载源码解析。collect/collectmix当前仅支持当前已登录 Cookie 对应账号且必须单独使用不能和post/like/mix/music混用。increase当前仅支持post/like/mix/music收藏夹模式不支持增量截断。直播录制 FLV 可直接播放HLS 源只保存 playlist 文件需要用 ffmpeg 后处理。webcast 直播接口未覆盖所有场景视为 experimental。二、快速开始从安装到跑通第一个下载任务1) 环境准备Python 3.8macOS / Linux / Windows2) 安装依赖pip install -r requirements.txt如需浏览器兜底或自动获取 Cookie额外安装 Playwright 及 Chromiumpip install playwright python -m playwright install chromium3) 复制配置cp config.example.yml config.ymlconfig.example.yml 是仓库自带的完整示例配置注释详细包含命名模板、画质选项、评论采集、直播录制、通知、REST 服务等全部可选项的说明。4) 获取 Cookie推荐自动方式python -m tools.cookie_fetcher --config config.yml登录抖音后回到终端按 Enter程序会自动把 Cookie 写入配置。Cookie 失效时重新执行该命令即可详见工具实现。5) Docker 部署可选docker build -t douyin-downloader . docker run -v $(pwd)/config.yml:/app/config.yml -v $(pwd)/Downloaded:/app/Downloaded douyin-downloader源码视角入口调用链从源码结构看整个 CLI 的启动链路非常清晰python run.py直接导入并调用 cli/main.py 的main()main()通过 argparse 解析命令行参数后调用main_async()完成配置加载、Cookie 校验、数据库初始化和逐链接下载cli/main.py。因此python run.py -c config.yml与直接运行python -m cli.main -c config.yml效果等价run.py 只是做了项目根目录的sys.path注入与工作目录切换。三、最小可用配置逐项拆解以下是最小可用配置可直接复制使用每个字段都能在上游默认配置中找到对应默认值与取值范围link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx path: ./Downloaded/ mode: - post number: post: 0 collect: 0 collectmix: 0 thread: 5 retry_times: 3 proxy: database: true database_path: dy_downloader.db progress: quiet_logs: true cookies: msToken: ttwid: YOUR_TTWID odin_tt: YOUR_ODIN_TT passport_csrf_token: YOUR_CSRF_TOKEN sid_guard: browser_fallback: enabled: true headless: false max_scrolls: 240 idle_rounds: 8 wait_timeout_seconds: 600 transcript: enabled: false model: gpt-4o-mini-transcribe output_dir: response_formats: [txt, json] api_url: https://api.openai.com/v1/audio/transcriptions api_key_env: OPENAI_API_KEY api_key: 配置加载与合并的源码细节从 config/config_loader.py 的实现可以确认三层配置合并顺序先以DEFAULT_CONFIG深拷贝为基底再逐层用 YAML 配置文件、环境变量覆盖。因此你只写关心的字段即可其余全部走默认值。值得注意的几个机制环境变量覆盖支持DOUYIN_COOKIE整串 Cookie、DOUYIN_PATH下载目录、DOUYIN_THREAD并发数、DOUYIN_PROXY代理适合容器化或 CI 场景免改配置注入config/config_loader.py。mix/allmix 别名归一化_normalize_mix_aliases会把number与increase两个区块里的allmix视为mix的兼容别名并同步归一若两者同时显式给出且值冲突会打 warning 并以mix为准config/config_loader.py。这也解释了 README 中allmix运行时会归一化到mix的限制说明。配置校验validate()会强制thread 1、retry_times 0非法时回退默认值 5 / 3并对start_time/end_time做YYYY-MM-DD格式校验格式非法会清空该字段config/config_loader.py。Cookie 多来源get_cookies()支持cookies字典、整串 Cookie 字符串、auto_cookie自动加载依次探测config/cookies.json、.cookies.json并统一做脱敏清洗config/config_loader.py。未被最小配置展示但值得关注的默认项在默认配置中还有一批重要参数README 的关键配置表之外也建议了解video_quality: highest视频画质档位选择。可选original原画探测代价是每条作品多一次探测请求超时 10s、highest最高转码档默认、lowest最低档省流量或指定1440p / 1080p / 720p / 540p / 480p / 360p匹配不到自动降级到最接近的可用档config/default_config.py。filename_template/folder_template命名模板默认{date}_{title}_{id}可用变量包括{id} {title} {author} {author_id} {date} {year} {month} {day} {time} {timestamp} {type} {mode}模板中必须包含{id}以避免重名覆盖。author_dir: nickname作者目录层命名方式可选nickname昵称默认、sec_uid稳定唯一、nickname_uid昵称_sec_uid推荐重度用户。切换只影响后续下载不会迁移已存在目录。group_by_mode: true是否按下载模式post/like/mix…再分一层子文件夹。rate_limit: 2API 请求速率限制请求/秒与thread并发下载数互相配合。redownload_missing_files: true增量任务磁盘主文件缺失时是否重新下载。video / music / cover / avatar / json附加资源开关默认只保存视频本体封面/音乐/头像/JSON 元数据按需打开避免平白多出几倍文件和请求。四、命令行使用方式与参数详解使用配置文件运行python run.py -c config.yml命令行追加参数python run.py -c config.yml \ -u https://www.douyin.com/video/7604129988555574538 \ -t 8 \ -p ./Downloaded-u传入的链接会追加到配置文件link列表末尾已存在则不重复追加-t/-p会覆盖配置中的thread/pathcli/main.py。参数说明参数说明-u, --url追加下载链接可重复传入-c, --config指定配置文件默认config.yml-p, --path指定下载目录-t, --thread指定并发数--show-warnings显示 warning/error 日志-v, --verbose显示 info/warning/error 日志--hot-board [N]拉取抖音热搜榜并导出 JSONL可选上限 N--search KEYWORD按关键词搜索作品并导出 JSONL--search-max N--search场景下最多拉取条数默认 50--serve以 REST API 服务模式运行需要pip install fastapi uvicorn--serve-host HOSTREST 服务监听地址默认 127.0.0.1--serve-port PORTREST 服务监听端口默认 8000--version显示版本号单链接下载的核心流程源码级从 cli/main.py 的download_url()可以看到一个链接从进入到完成的完整调用链这也是理解整个工具架构的最佳入口初始化组件创建FileManager文件落盘、RateLimiter默认 2 请求/秒、RetryHandler默认重试 3 次、QueueManager默认 5 并发。短链解析is_short_url()识别v.douyin.com/v.iesdouyin.com/ 裸 host 短链调用api_client.resolve_short_url()还原为完整链接。URL 类型解析URLParser.parse()根据路径段识别video / user / collection / gallery / music / live / live_replay等类型并抽取对应 ID如/video/(\d)提取 aweme_id、/user/([A-Za-z0-9_-])提取 sec_uid实现见 core/url_parser.py。能力门禁对已识别但永远不会有下载器的类型如lvdetail抖音放映厅影视因 DRM 加密无法获取可播放成片提前拦截并给出真实原因而不是报未找到下载器core/downloader_factory.py。工厂创建下载器DownloaderFactory.create()按类型分发到VideoDownloader视频/图文、UserDownloader作者主页、MixDownloader合集、MusicDownloader音乐、LiveDownloader/LiveReplayDownloader直播与回放core/downloader_factory.py。执行下载并记录历史下载完成后若database: true把 URL、类型、成功/失败/跳过计数及脱敏后的配置快照写入 SQLite 历史表自动剔除cookies、transcript等敏感字段。自动重登录整个下载被_run_with_relogin包裹捕获LoginRequiredError后自动打开浏览器重新登录一次并重试非交互环境则提示手动更新 Cookiecli/main.py。对于作者主页这类多模式批量任务下载策略由 core/user_mode_registry.py 中的注册表按post / like / mix / music / collect / collectmix六种模式分发到各自的策略实现。五、典型下载场景实操下载单个视频link: - https://www.douyin.com/video/7604129988555574538下载单个图文link: - https://www.douyin.com/note/7341234567890123456下载单个合集link: - https://www.douyin.com/collection/7341234567890123456下载单个音乐link: - https://www.douyin.com/music/7341234567890123456音乐模式优先保存原声文件缺失时自动回退到该音乐下首条作品。批量下载作者主页作品link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post number: post: 50批量下载作者点赞作品link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - like number: like: 0 # 0 表示全量下载同时下载多种模式link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post - like - mix - music跨模式自动去重同一个 aweme_id 在不同模式下不会重复下载。批量下载当前登录账号收藏夹作品link: - https://www.douyin.com/user/self?showTabfavorite_collection mode: - collect number: collect: 0批量下载当前登录账号收藏合集link: - https://www.douyin.com/user/self?showTabfavorite_collection mode: - collectmix number: collectmix: 0录制直播实验性link: - https://live.douyin.com/123456789 # 也支持 /follow/live/{room_id} live: max_duration_seconds: 3600 # 0 录到主播下播 chunk_size: 65536 idle_timeout_seconds: 30录制的 FLV 会保存在Downloaded/{作者}/live/下并附带*_room.json直播间元数据快照。主播下播、网络空闲或 CtrlC 中断时已录制的字节会被保留.tmp 文件自动提升为正式文件。从直播录制实现可以看到其技术路径通过/webcast/room/web/enter/获取 stream_urlflv_pull_url含 SD/HD/FULL_HD/ORIGIN 多档hls_pull_url_map含 HD1/HD2/HD3按清晰度优先级选择最高清可用流并优先 FLV单文件落盘简单使用 aiohttp 分块写入.flv临时文件完成后原子重命名不依赖 ffmpeg不处理多人房间/连麦切换不采集弹幕。采集作品评论comments: enabled: true include_replies: false # 设为 true 会多拉每条评论的二级回复额外请求量 max_comments: 500 # 0 不限 page_size: 20会在媒体文件旁生成{date}_{title}_{aweme_id}_comments.json。导出热搜榜快照python run.py --hot-board 30 -p ./Downloaded # 输出./Downloaded/hot_board/20260424_221530.jsonl关键词搜索python run.py --search 猫咪 --search-max 100 -p ./Downloaded # 输出./Downloaded/search/猫咪_20260424_221530.jsonl热搜与搜索子命令的落地实现在 core/discovery.py且这两个子命令允许在config.yml不存在时配合--path以默认配置直接运行cli/main.py。以 REST API 服务模式运行pip install fastapi uvicorn # 一次性可选依赖 python run.py --serve --serve-port 8000接口一览MethodPath说明POST/api/v1/download提交{url: ...}返回{job_id, status}GET/api/v1/jobs/{job_id}查询指定 job 的状态/计数GET/api/v1/jobs列出最近的 job按 TTL 容量剪裁GET/api/v1/health健康探针完成态的 job 会按 TTL默认 24 小时 最大数量默认 500自动剪裁in-flight 的 job 永不被裁掉。可通过server.max_jobs/server.job_ttl_seconds调整服务实现在 server/app.py。完成后发送通知notifications: enabled: true on_success: true on_failure: true providers: - type: bark url: https://api.day.app/YOUR_DEVICE_KEY sound: bell - type: telegram bot_token: 123456:ABC... chat_id: 987654321 - type: webhook # 企业微信/飞书/钉钉 bot URL 同样可用 url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxx extra_body: msgtype: text所有启用的 provider 会并发推送单个 provider 失败不会阻塞主下载流程。从 cli/main.py 的通知分发逻辑看消息会区分全部成功 / 部分失败 / 全部失败三种级别通知失败只记日志不影响主流程。增量下载只下载新作品increase: post: true database: true # 增量模式依赖数据库记录各模式均可独立开关true时仅当当前下载目录下已存在该作品非空的主媒体文件才跳过设为false则强制重新下载并以原子方式覆盖当前 number/date/media 筛选范围内的文件。全量抓取不限制数量number: post: 0六、可选功能视频转写transcript当前实现仅对视频作品生效图文不会生成转写。1) 开启方式transcript: enabled: true model: gpt-4o-mini-transcribe output_dir: # 留空: 与视频同目录非空: 镜像到指定目录 response_formats: - txt - json api_key_env: OPENAI_API_KEY api_key: # 可直接填或使用环境变量推荐通过环境变量提供密钥export OPENAI_API_KEYsk-xxxx2) 输出文件启用后会生成xxx.transcript.txtxxx.transcript.json若database: true会在数据库transcript_job表记录状态success/failed/skipped。补充一点默认配置细节transcript.upload_audio_only默认为true即本地先经 ffmpeg 抽取单声道 mp3 再上传转写接口可节省带宽并规避 OpenAI 单文件 25 MiB 上限config/default_config.py。七、关键配置项速查表配置项说明mode支持post/like/mix/music当前登录收藏夹模式额外支持单独使用的collect/collectmixnumber.post/like/mix/music/collect/collectmix各模式下载数量限制0 为不限increase.post/like/mix/music各模式增量开关start_time/end_time时间过滤格式YYYY-MM-DDfolderstyle按作品维度创建子目录browser_fallback.*post翻页受限时启用浏览器兜底progress.quiet_logs进度阶段静默日志减少刷屏transcript.*视频下载后的可选转写proxy为 API 请求和媒体下载设置 HTTP/HTTPS 代理例如http://127.0.0.1:7890comments.*按作品采集评论默认关闭live.*直播录制参数max_duration_seconds / chunk_size / idle_timeout_secondsnotifications.*下载完成后 Bark/Telegram/Webhook 推送server.*REST API 服务调优max_jobs、job_ttl_secondsdatabase启用 SQLite 去重和历史记录database_pathSQLite 文件路径默认在当前工作目录生成dy_downloader.dbthread并发下载数retry_times失败重试次数关于progress.quiet_logs有一个值得了解的实现细节当它为true且未加-v/--show-warnings时主流程会在进度渲染期间把控制台日志级别临时提升到CRITICAL下载结束再恢复从而避免大量错误日志触发 Rich 反复重绘导致屏幕出现重复块cli/main.py。八、输出目录结构与重新下载机制输出目录默认folderstyle: true且database_path: dy_downloader.db时工作目录/ ├── config.yml ├── dy_downloader.db # database: true 时默认生成在这里 └── Downloaded/ ├── download_manifest.jsonl └── 作者名/ ├── post/ │ └── 2024-02-07_作品标题_aweme_id/ │ ├── ...mp4 │ ├── ..._cover.jpg │ ├── ..._music.mp3 │ ├── ..._data.json │ ├── ..._avatar.jpg │ ├── ..._comments.json # comments.enabled 时生成 │ ├── ...transcript.txt │ └── ...transcript.json ├── like/ │ └── ... ├── mix/ │ └── ... ├── music/ │ └── ... ├── collect/ │ └── ... ├── collectmix/ │ └── ... └── live/ # 录制直播时生成 └── 2026-04-24_2215_直播标题_房间号/ ├── ...flv └── ..._room.json--hot-board会在Downloaded/hot_board/生成20260424_221530.jsonl格式的快照--search会在Downloaded/search/生成关键词_时间戳.jsonl。重新下载程序通过数据库记录 本地文件双重检查判断是否跳过已下载内容。要强制重新下载需要按场景清理数据重新下载特定作品# 删除本地文件文件名中包含 aweme_id rm -rf Downloaded/作者名/post/*_aweme_id/ # 删除数据库记录 sqlite3 dy_downloader.db DELETE FROM aweme WHERE aweme_id aweme_id;重新下载某个作者的全部作品rm -rf Downloaded/作者名/ sqlite3 dy_downloader.db DELETE FROM aweme WHERE author_name 作者名;全部从零重新下载rm -rf Downloaded/ rm dy_downloader.db注意只删数据库不删文件不会触发重新下载——程序会扫描本地文件名中的 aweme_id 进行去重。只删文件不删数据库会触发重新下载数据库中有记录但文件不存在时视为需要重新下载。去重与历史记录的源码依据SQLite 去重的核心表aweme以aweme_id UNIQUE为主键记录作品类型、标题、作者、创建/下载时间、文件路径与元数据并通过 WAL 日志模式 synchronousNORMAL兼顾并发读写与写入性能storage/database.py。下载完成后若database: truecli/main.py 还会把脱敏后的运行配置快照写入download_history表便于回溯某次批量任务用了什么参数。九、测试与常见问题运行测试推荐python3 -m pytest -q直接运行pytest -q也受支持。仓库tests/目录覆盖了配置加载、URL 解析、各下载器、去重、直播录制、转写、通知、代理透传、命名模板、时间范围过滤等大量行为例如 test_url_parser.py、test_config_loader.py、test_downloader_factory.py、test_live_downloader.py、test_server.py。常见问题1) 只能抓到 20 条作品怎么办这是翻页风控的常见现象。确保browser_fallback.enabled: truebrowser_fallback.headless: false浏览器弹窗出现后手动完成验证不要立即关闭窗口2) 进度条出现重复刷屏怎么办默认progress.quiet_logs: true会在进度阶段静默日志。调试时再临时加--show-warnings或-v。3) Cookie 失效怎么办重新执行python -m tools.cookie_fetcher --config config.yml4) 为什么没有生成 transcript 文件请依次检查transcript.enabled是否为true是否下载的是视频图文不转写OPENAI_API_KEY或transcript.api_key是否有效response_formats是否包含txt或json5) 如何查看下载历史sqlite3 dy_downloader.db SELECT aweme_id, title, author_name, datetime(download_time, unixepoch, localtime) FROM aweme ORDER BY download_time DESC LIMIT 20;十、使用边界与许可本项目仅用于技术研究、学习交流与个人数据管理请在合法合规前提下使用不得用于侵犯他人隐私、版权或其他合法权益不得用于任何违法违规用途使用者应自行承担因使用本项目产生的全部风险与责任如平台规则、接口策略变更导致功能失效属于正常技术风险。项目采用 MIT License详见 LICENSE。英文文档见 README.md更多项目背景与桌面版 Douzy 的界面能力可查阅英文文档对应章节。【免费下载链接】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），仅供参考