douyin-downloader：抖音无水印批量下载的本地化方案-开发者社区

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 跑通第一个视频的体验非常具体：这是一个抖音无水印下载工具，批量流程也一并验证——把抖音短链粘贴进配置，执行python run.py -c config.yml，约 30 秒后下载目录里多出四样东西：一条无水印 mp4、一个原声音乐文件、一张高清封面图、一份作品元数据 JSON。接下来，同样的流程可以指向任何创作者的主页：作品按时间倒序逐页抓取，进度条、失败重试、去重全部由程序处理，你只需要盯着数字滚动。下面按能力分层、启动路径、角色场景、内部机制四个部分，说清楚这个工具能做什么、怎么开始。

📥 三层能力清单：拉什么、存什么、怎么管

下载层：决定拉取的对象

单作品下载：粘贴视频、图文、合集或音乐链接即可运行，自动解析短链并挑选无水印源、自动选最高码率。
主页批量下载：给出主页链接加 mode，作品按发布时间倒序翻页拉取，number.post控制数量上限，0 表示全量。
直播录制：粘贴live.douyin.com房间链接，实时拉流录制，主播下播时已录分段自动落盘。
热搜与搜索：--hot-board 30和--search "关键词"两条命令，结果以 JSONL 快照落盘，方便做数据研究。

资产层：视频之外的产物

原声音乐：music: true时抽取作品的音轨，独立存为 mp3，与视频分离保存。
封面与头像：高清封面图和创作者头像随作品一起保存，不需要手动截图。
元数据 JSON：每个作品生成_data.json，含标题、发布时间、互动数、作者信息。
评论导出：comments.enabled打开后，评论（含二级回复）以结构化 JSON 存在媒体文件旁。

管控层：批量任务如何可控

SQLite 去重：dy_downloader.db记录每个 aweme_id，重跑同一主页时已下载项自动跳过。
断点续传：下载过程做 Content-Length 比对，不完整文件自动清理并重试，中断后重跑同一配置即可继续。
时间窗口过滤：start_time/end_time限定只拉取指定区间内发布的作品。
增量模式：increase.post: true时只拉取上次之后的新作品，依赖数据库记录判断边界。
命名模板：folderstyle按作品维度建子目录，目录名按日期_标题_aweme_id生成，同构目录方便归档。

🚀 最短路径：五条命令跑通一个视频

以下五条 shell 完成从克隆环境到首次下载，Cookie 获取只需运行python -m tools.cookie_fetcher扫码即可，无需手动从浏览器复制：

git clone https://gitcode.com/GitHub_Trending/do/douyin-downloader cd douyin-downloader pip install -r requirements.txt cp config.example.yml config.yml python -m tools.cookie_fetcher --config config.yml && python run.py -c config.yml

扫码后 Cookie 自动写入配置并只保存在本地。最后一条命令读取配置中的链接开始下载。完整字段见 config.example.yml。需要注意：平台风控收紧时部分 API 路径会被限制，保持browser_fallback开启是默认建议。

按角色分场景：四套配置姿势

如果你是内容搬运/收藏者

你关心某个创作者的主页。mode 设为 post 并给出时间窗口，只拉取指定日期之后发布的作品；database: true之后，同一主页重跑只会补齐新作品，增量下载不会重复拉取已保存的内容：

mode: [post] start_time: "2026-08-01" # 其余字段保持默认值

主页作品按创作者加日期归档到子目录，下载历史随时可以查库核对。

如果你是音乐/封面采集者

视频本身不需要。把music: true与cover: true打开，每个作品只产出原声文件和封面图，适合搭建素材库，磁盘占用也最低。

如果你是直播录制者

粘贴房间链接并给录制设时长上限。max_duration_seconds表示录到多少秒后主动停止，0 表示一直录到主播下播：

live: max_duration_seconds: 3600 # 0 表示录到主播下播，其余字段保持默认值

FLV 文件可直接播放；HLS 源只保存 playlist，需要 ffmpeg 后处理。主播下播、网络空闲、Ctrl+C 中断都会保留已录分段。

如果你是自动化/集成开发者

以 REST API 模式运行，通过 HTTP 接口提交与查询任务：

python run.py --serve --serve-port 8000

启动后向POST /api/v1/download提交{"url": "..."}得到 job_id，再用GET /api/v1/jobs/{job_id}查状态与计数。完成态任务按 TTL 自动剪裁，进行中的任务不会被裁掉，适合排队式集成。

🔍 去重与直播录制是怎么做到的

去重是「数据库记录 + 文件名交叉校验」双重机制。storage/database.py 里的 aweme 表为每个作品维护一条以 aweme_id 为键的记录；重跑时先查库，命中且 file_path 非空才跳过。同时程序还会扫描本地文件名中嵌入的 aweme_id 交叉核对：数据库丢了，已有文件不会被重下；删了文件但库里还有记录，该作品会重新拉取。这解释了「只删库不删文件不触发重下，只删文件不删库则触发重下」的行为。

直播录制是「先取流、再分块写、异常时提升文件」三步。进入房间时通过 webcast 接口拿到流地址集合：flv_pull_url优先，在 ORIGIN 到 SD 之间取最高画质，因为单文件落盘最简单；只有 HLS 可用时保存 playlist。字节流以 64KB 分块写入.tmp临时文件，主播下播、网络空闲、Ctrl+C 走的是同一条路径：只要已写入字节大于 0，.tmp就被原子提升为正式文件。录到一半也比零字节有用，这是它的保留策略；只有 HTTP 4xx 或零字节才丢弃。

⚠️ 排障：现象 → 原因 → 操作

403 Forbidden 或「未登录」报错→ Cookie 过期（有效期通常 7–15 天） → 重跑python -m tools.cookie_fetcher扫码更新。
翻页停在 20 条→ API 分页被风控限制 →browser_fallback.enabled: true且headless: false，等浏览器弹窗手动完成验证，不要立即关窗。
下载中断或文件不完整→ 网络抖动或速率限制 → 程序按 Content-Length 比对自动清理不完整文件并重试，仍失败就重跑同一配置续传，或调低thread并发数。