企业官网建设流程全解析

抖音下载器 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 提供独立工作台，支持多链接队列、任务状态跟踪、本地下载档案与快速重新下载。

已支持功能

当前限制说明

• 浏览器兜底当前仅针对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.8+
• macOS / Linux / Windows

2) 安装依赖

pip install -r requirements.txt

如需浏览器兜底或自动获取 Cookie，额外安装 Playwright 及 Chromium：

pip install playwright python -m playwright install chromium

3) 复制配置

cp config.example.yml config.yml

config.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: 2：API 请求速率限制（请求/秒），与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/path（cli/main.py）。

参数说明

单链接下载的核心流程（源码级）

从 cli/main.py 的download_url()可以看到一个链接从进入到完成的完整调用链，这也是理解整个工具架构的最佳入口：

1. 初始化组件：创建FileManager（文件落盘）、RateLimiter（默认 2 请求/秒）、RetryHandler（默认重试 3 次）、QueueManager（默认 5 并发）。
2. 短链解析：is_short_url()识别v.douyin.com/v.iesdouyin.com/ 裸 host 短链，调用api_client.resolve_short_url()还原为完整链接。
3. 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。
4. 能力门禁：对已识别但永远不会有下载器的类型（如lvdetail抖音放映厅影视，因 DRM 加密无法获取可播放成片）提前拦截并给出真实原因，而不是报"未找到下载器"（core/downloader_factory.py）。
5. 工厂创建下载器：DownloaderFactory.create()按类型分发到VideoDownloader（视频/图文）、UserDownloader（作者主页）、MixDownloader（合集）、MusicDownloader（音乐）、LiveDownloader/LiveReplayDownloader（直播与回放）（core/downloader_factory.py）。
6. 执行下载并记录历史：下载完成后若database: true，把 URL、类型、成功/失败/跳过计数及脱敏后的配置快照写入 SQLite 历史表（自动剔除cookies、transcript等敏感字段）。
7. 自动重登录：整个下载被_run_with_relogin包裹，捕获LoginRequiredError后自动打开浏览器重新登录一次并重试；非交互环境则提示手动更新 Cookie（cli/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?showTab=favorite_collection mode: - collect number: collect: 0

批量下载当前登录账号收藏合集

link: - https://www.douyin.com/user/self?showTab=favorite_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直播间元数据快照。主播下播、网络空闲或 Ctrl+C 中断时，已录制的字节会被保留（.tmp 文件自动提升为正式文件）。

从直播录制实现可以看到其技术路径：通过/webcast/room/web/enter/获取 stream_url（flv_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

接口一览：

完成态的 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?key=xxx 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_KEY="sk-xxxx"

2) 输出文件

启用后会生成：

• xxx.transcript.txt
• xxx.transcript.json

若database: true，会在数据库transcript_job表记录状态（success/failed/skipped）。补充一点默认配置细节：transcript.upload_audio_only默认为true，即本地先经 ffmpeg 抽取单声道 mp3 再上传转写接口，可节省带宽并规避 OpenAI 单文件 25 MiB 上限（config/default_config.py）。

七、关键配置项速查表

关于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 日志模式 +synchronous=NORMAL兼顾并发读写与写入性能（storage/database.py）。下载完成后若database: true，cli/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: true
• browser_fallback.headless: false
• 浏览器弹窗出现后手动完成验证，不要立即关闭窗口

2) 进度条出现重复刷屏怎么办？

默认progress.quiet_logs: true会在进度阶段静默日志。调试时再临时加--show-warnings或-v。

3) Cookie 失效怎么办？

重新执行：

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

4) 为什么没有生成 transcript 文件？

请依次检查：

• transcript.enabled是否为true
• 是否下载的是视频（图文不转写）
• OPENAI_API_KEY（或transcript.api_key）是否有效
• response_formats是否包含txt或json

5) 如何查看下载历史？

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