douyin-downloader 抖音下载工具 4 步上手教程：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

douyin-downloader 是一款免费开源的抖音无水印下载工具：粘贴单条视频链接，或整批保存某个作者的主页作品、合集、点赞列表与背景音乐。它带下载进度条、自动重试，并用本地 SQLite 记录历史，实现增量去重。本文按"最短成功路径 → 能力范围 → 增量机制 → 故障处理"的顺序，带你把每一环跑通。

从克隆仓库到第一条视频落地：四步最短路径

这四步走完，你的本地目录里就会躺着第一个无水印视频文件。

第一步，拿到源码并装依赖。终端执行（需要 Python 3.9+，支持 Windows、macOS、Linux）：

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

playwright 与 chromium 是浏览器兜底机制依赖的运行时，后面接口被验证拦住时会用到，现在装好即可。

第二步，把配置模板复制成本地配置：

cp config.example.yml config.yml

第三步，领取 Cookie。抖音的接口只在"已登录"的会话下才完整返回数据，Cookie 就是你账号的登录态凭证，必须让工具带着它去请求。运行下面这条命令：

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

脚本会打开一个浏览器窗口，扫码登录你的抖音账号，然后回到终端按 Enter，Cookie 就被写进config.yml了——文件里cookies:下面出现一串真实的键值对，就表示这一步成了。✅

第四步，下载第一条。从 App 里复制任意一条分享链接，执行：

python run.py -u "https://v.douyin.com/xxxxxxx"

-u会把这条链接追加到配置里的link列表上。工具先解析这条短链拿到真实视频 ID，再去掉水印拉取源文件，成品按"作者名 / 日期_标题_视频ID"归入Downloaded/目录。

⚠️ 需要提前知道：抖音当前对 CLI 的单条、合集、音乐、点赞等接口有请求验证，部分链接会下载失败。工具内置了 Playwright 浏览器兜底可以试试，但不保证成功；日常高频下载建议用同一项目提供的 Douzy 桌面版，命令行版更适合脚本化与批量场景。

能力范围：单条、主页、合集、音乐与直播分别怎么下

工具的能力由config.yml中的mode、link和若干开关决定，常见场景按下表取用：

除下载本身，还有一组可选的深加工能力：

• 评论采集：comments.enabled: true后，每个作品额外生成一份*_comments.json，include_replies控制是否带上回复；
• 视频转写：transcript.enabled: true，通过api_key_env指定 API Key 所在的环境变量名；
• 完成通知：notifications支持 bark、telegram、webhook 三类渠道，成功或失败都可以推送；
• REST API 服务：python -m pip install fastapi uvicorn后执行python run.py --serve --serve-port 8000；
• 热搜与搜索：python run.py --hot-board 30、python run.py --search "关键词" --search-max 50，结果输出为 JSONL。

落盘方式也可以按自己的习惯整形：filename_template/folder_template决定文件名与文件夹模板（变量如{date}{title}{id}，模板必须包含{id}避免重名覆盖）；author_dir可选nickname、sec_uid或nickname_uid；download_pinned控制是否连带置顶作品；author_url与homepage_screenshot可在作者目录里留下一份主页地址文本或首屏截图。

Douzy 桌面版与 CLI 出自同一项目，支持抖音、TikTok、YouTube、Telegram、X，粘贴链接即可下载、跟踪任务并管理本地作品档案：

增量下载与去重：长期备份作者主页的核心机制

要解决的问题：长期跟踪一位作者时，如果每次都从头拉一遍全部作品，带宽、时间和磁盘都会被无谓消耗，旧文件还可能被反复覆盖。

怎么配：开启增量开关，并决定"记录在、但文件没了"时怎么办：

increase: post: true # 跳过已判定下载过的作品（like/mix/music 各有对应开关） redownload_missing_files: true # 主文件缺失或为空时补下；false 则凭历史记录直接跳过 database: true database_path: dy_downloader.db

判定规则：工具一边查 SQLite 下载历史，一边检查磁盘上的主媒体文件是否非空，两者共同决定跳过还是补下。想让某批作品强制重下，把对应increase开关改为false即可——它会重新下载并覆盖当前筛选范围内的文件，不需要清空数据库。

跑起来什么样：终端里每个任务实时刷新进度条与耗时；已下载的作品被直接标记跳过，磁盘上按下面的结构生长：

Downloaded/ ├── download_manifest.jsonl # 下载清单，每行一条 JSON，随任务追加 └── 作者名/ └── post/ └── 2024-02-07_作品标题_aweme_id/ ├── 2024-02-07_作品标题_aweme_id.mp4 ├── 2024-02-07_作品标题_aweme_id_cover.jpg # 需 cover: true ├── 2024-02-07_作品标题_aweme_id_music.mp3 # 需 music: true └── 2024-02-07_作品标题_aweme_id_data.json # 需 json: true

常见故障对照：信号、原因与动作

遇到下面这些现象时，先对号入座再动手：

拿不准具体卡在哪一步时，加-v跑一遍拿详细日志：python run.py -c config.yml -v。

最后：边界与下一步

douyin-downloader 的价值在于把"下载、归档、去重"压缩成一套可重复执行的配置。请把它用于个人备份与学习研究，尊重创作者版权，勿将下载内容二次传播或商用。打开终端，粘贴你的第一条链接，跑起来。

想细读全部字段，看 config.example.yml；想看下载主流程与 URL 解析的实现，进 core/ 目录翻源码。

【免费下载链接】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