企业官网建设流程全解析

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 是一款实用的抖音批量下载工具：无水印视频、图文、合集、音乐都能下，内置 SQLite 去重与磁盘增量更新。本文从克隆安装、获取 Cookie，讲到三类由浅入深的任务，帮你在一个小时内建立稳定的下载流程。

它能帮你做什么

上手前先明确工具的边界。核心能力与对应场景如下：

每项能力都对应独立的配置开关，不需要全部启用。

工作原理速览

了解底层流程，出问题时可以快速定位卡点。一次运行的主流程是：

config.yml 与命令行参数→链接解析→API 拉取→并发下载→落盘与历史记录。

具体来说，core/url_parser.py 先判断链接属于哪种类型：单作品、图文、合集、音乐还是用户主页，再决定走哪条下载路径。随后 API 客户端按 rate_limit（默认每秒 2 次请求，另加 0 到 0.5 秒随机抖动）拉取作品列表，由默认 5 个并发线程下载媒体文件。失败时 control/retry_handler.py 会按 1 秒、2 秒、5 秒的间隔重试最多 3 次。文件写盘后按 Content-Length 校验完整性，不完整的文件会被清理并重试。最后，记录写入 SQLite 数据库和 download_manifest.jsonl 清单。需要记住的一点：增量跳过判断依据的是本地主文件是否存在，而不是数据库——删掉文件，下次运行就会重新下载。

上手指南（最小可行路径）

完整流程共 4 步，含浏览器登录约 10 分钟。

环境要求：Python 3.8+；支持 macOS / Linux / Windows；浏览器兜底与自动获取 Cookie 需要先用 playwright 安装 chromium 浏览器。

第 1 步：克隆仓库并安装依赖

git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader pip install -r requirements.txt

预期看到依赖安装完成、无报错。网络慢时可换国内镜像源加速。

第 2 步：生成配置并填入链接

cp config.example.yml config.yml

config.example.yml 自带逐行注释。编辑 config.yml 时，至少要改两处：把 link 换成目标链接，把 number.post 设为想要的数量（0 表示不限制）。

第 3 步：获取 Cookie

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

终端会拉起浏览器窗口，在窗口内完成抖音登录，回到终端按回车，Cookie 就自动写回配置文件。

💡 提示：浏览器兜底功能需要额外安装 chromium：pip install playwright && python -m playwright install chromium；如果出口受限，可在配置文件的 proxy 字段填代理地址。

第 4 步：跑通第一次下载

python run.py -c config.yml

预期看到终端出现进度条，结束后输出成功与失败计数，文件落在./Downloaded/{作者名}/post/{日期}_{标题}_{id}/目录下。同一套后端还有一个桌面端 GUI（Douzy，目前为内测版本），链接下载界面如下：

图：粘贴抖音链接即可识别单作品、主页、合集类型并一键下载

三个典型任务

三个任务按复杂度递进，前一个的输出是后一个的前提。

任务一：下载单条视频（5 分钟）

目标：从一条链接拿到无水印视频文件，验证整条链路可用。

把 config.yml 的 link 换成单作品链接：

link: - https://www.douyin.com/video/7604129988555574538 # 单作品链接 number: post: 0 # 单链接下载，数量限制不生效 thread: 3 # 单条任务，低并发足够

执行python run.py -c config.yml等待完成。

完成标志：Downloaded/{作者名}/post/下出现对应作品目录，.mp4 可正常播放且无水印。

🔗 相关模块：core/url_parser.py、core/video_downloader.py

任务二：批量下载创作者作品并控制画质与增量（15 分钟）

单条链路通了，这一步切换到主页链接：批量取作品、限制数量、指定画质，并开启增量，让同一个配置可以反复执行。

link: - https://www.douyin.com/user/MS4wLjABAAAA6O7EZyfDRYXxJrUTpf91K3tmB4rBROkAw-nYMfld8ss mode: - post # 只取发布作品 number: post: 30 # 上限 30 条 increase: post: true # 下次运行跳过磁盘已有的作品 video_quality: 1080p # 固定画质档，匹配不到自动降到最接近档

运行同一条命令。创作者发布新作品后再执行一次，就只会下载新增的部分。

完成标志：post 目录下共 30 条作品；同一配置第二次运行时，绝大多数条目显示跳过，只下载新增项。

图：桌面端的关注界面会同步每位创作者的新作品数，可直接从列表触发下载

🔗 相关模块：core/user_modes/、storage/database.py

任务三：多模式全量收藏，带评论与元数据（30 分钟+）

单模式跑通后，把多模式、时间范围和数据附加项组合起来，形成一个可定期执行的收藏任务。

link: - https://www.douyin.com/user/MS4wLjABAAAA6O7EZyfDRYXxJrUTpf91K3tmB4rBROkAw-nYMfld8ss mode: - post # 作品 - like # 点赞 - mix # 合集 number: post: 0 # 不限 like: 0 mix: 0 start_time: "2025-01-01" # 只取此日期之后的作品 end_time: "2026-09-01" # 到此日期为止 json: true # 保存每条作品的元数据 JSON comments: enabled: true # 为每个作品抓取评论 max_comments: 200 # 每作品最多 200 条，控制请求量

三种模式之间会按作品 ID 跨模式去重，同一条内容不会下两次。收藏类的 collect / collectmix 模式必须单独使用，不能与上面四种混写，且只对当前 Cookie 所属账号生效。

任务结束后，用数据库核对本次结果：

sqlite3 dy_downloader.db "SELECT aweme_id, title, author_name FROM aweme ORDER BY download_time DESC LIMIT 5;"

完成标志：作者目录下出现 post/、like/、mix/ 三个子目录；每个作品文件旁有 _data.json 和 _comments.json；数据库查询能返回最近的下载记录。

图：桌面端的收藏与喜欢界面，对应 collect / collectmix 模式，整个收藏夹可一键下载

🔗 相关模块：core/comments_collector.py、core/metadata.py

关键配置详解

前三个任务用到了几个高频参数，这里把最影响体验的 7 项集中说明，每项都附了判断依据：

如果只记一条原则：下载失败时，先降并发与频率，而不是继续加大。

thread: 5 # 并发下载数，普通网络取 3–5 retry_times: 3 # 失败重试次数，退避间隔 1/2/5 秒 rate_limit: 2 # 请求频率上限，不宜调高 video_quality: highest # 最高转码档；改 original 每条多一次探测 increase: post: true # 跳过磁盘已有主文件的条目 browser_fallback: enabled: true # 翻页受限时打开浏览器兜底 headless: false # 显示浏览器窗口，便于人工过验证码 progress: quiet_logs: true # 进度阶段抑制日志刷屏

性能与稳定性

任务跑起来之后，性能问题基本落在并发、重试、容量三个旋钮上。

并发与限速

工具在两层做了控制：thread 决定同时下载几个文件（默认 5），rate_limit 决定 API 请求频率（默认每秒 2 次，另加 0 到 0.5 秒随机抖动，避免固定节奏）。日常使用建议thread: 3–5、rate_limit: 2的组合。频繁出现风控提示或超时时，先把 thread 降到 3，观察两三轮运行再决定是否回调。

失败与重试

单次请求失败会进入重试循环：最多 3 次重试，间隔 1 秒、2 秒、5 秒依次拉长。文件下载完成后会按 Content-Length 校验大小，不完整的文件自动清理并重试。翻页受限时，browser_fallback 拉起真实浏览器继续抓取，期间可以人工完成验证码。单条作品重试全部失败不会中断整个任务，最终输出失败计数；用同一配置再跑一遍，增量机制会只补失败的条目。

资源占用

内存占用较低，主要来自并发下载缓冲。磁盘以视频文件为主：只保存视频本体时，单条作品通常占数 MB 到数十 MB；再开启封面、音乐、JSON、评论后，文件数量会成倍增加。全量抓取前，按「条数 × 单条体积」预留容量更稳妥。SQLite 数据库与 download_manifest.jsonl 清单都很小，千条作品后一般仍在 MB 量级，不用为此担心。

图：任务中心界面：每个任务的成功/失败计数、重试入口与输出目录位置一目了然

常见问题

以下 5 个问题覆盖了实际使用中的多数卡点，都可以通过改配置或重跑一条命令解决。

只拉到 20 条左右就停了

原因：平台对翻页做了风控，API 返回的页数少于实际。

1. 确认browser_fallback.enabled: true且headless: false。
2. 重新运行任务，浏览器弹出时人工完成验证，不要提前关闭窗口。
3. 若仍受限，把 thread 降到 3 再跑。

⏱ 预计解决时间：约 5 分钟

下载内容为空或请求被拒

原因：Cookie 过期或登录态失效。

1. 运行python -m tools.cookie_fetcher --config config.yml重新获取。
2. 确认配置文件里 cookies 字段已更新。
3. 重新运行下载任务。

⏱ 预计解决时间：约 3 分钟

第二次运行没有跳过已下载的内容

原因：增量判断依赖本地主文件，文件被手动删除或清空会触发重下；或者配置里 increase 被设成了 false。

1. 检查 increase 中对应模式为 true。
2. 检查 Downloaded 下对应作品的主文件是否还在、是否为空文件。
3. 想强制重下时，把该模式的 increase 设为 false，会在当前筛选范围内覆盖。

⏱ 预计解决时间：约 2 分钟

用 collect 或 collectmix 报错

原因：收藏类模式必须单独使用，不能与 post / like / mix / music 混在一起。

1. 单独建一个配置文件，mode 只写 collect（或 collectmix）。
2. link 使用自己收藏夹页面的链接。
3. 注意该模式只对当前 Cookie 所属账号生效。

⏱ 预计解决时间：约 2 分钟

转写文件没有生成

原因：转写只对视频作品生效，图文作品不产生转写；同时需要有效的 API 密钥。

1. 确认transcript.enabled: true，且作品是视频而非图文。
2. 确认 OPENAI_API_KEY 环境变量已设置，或 transcript.api_key 已填写。
3. 确认 response_formats 包含 txt 或 json。

⏱ 预计解决时间：约 5 分钟

进阶探索

日常使用顺了之后，可以考虑让工具接入更大的工作流。

方向一：自动化

如果希望定期同步创作者更新，把python run.py -c config.yml放进系统定时任务（cron），配合 increase 增量开关，默认行为就是只取新增内容。服务器部署场景，仓库自带 Dockerfile，构建镜像后把配置文件和下载目录挂载进去即可。

方向二：二次开发

想改请求层的行为（签名、分页、风控应对），入口在 core/api_client.py；主页各模式（post / like / mix / music）的策略类都放在 core/user_modes/，按模式拆文件，改单个模式不会波及其他。

方向三：生态集成

需要与其他系统对接时，可用python run.py --serve --serve-port 8000启动 REST API 服务（需另装 fastapi 与 uvicorn），通过 HTTP 提交链接、轮询任务状态，实现在 server/app.py。完成通知支持 bark / telegram / webhook 三种渠道，见 utils/notifier.py；download_manifest.jsonl 是逐行 JSON，可直接喂给下游分析脚本。

从克隆安装、获取 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