DouK-Downloader 抖音 TikTok 作品下载与数据采集完整指南：3 分钟跑通首次下载

DouK-Downloader 抖音 TikTok 作品下载与数据采集完整指南：3 分钟跑通首次下载

【免费下载链接】TikTokDownloader抖音 / TikTok 平台作品下载/数据采集工具项目地址: https://gitcode.com/GitHub_Trending/ti/TikTokDownloader

DouK-Downloader（历史名称 TikTokDownloader）是一款基于 HTTPX 异步请求库的抖音 / TikTok 作品下载与数据采集工具。本文带你完成环境搭建、Cookie 写入与首次作品下载，并拆解到源码级的关键实现。

一、它解决什么问题

核心痛点一句话：免抓包脚本地批量获取抖音 / TikTok 作品文件与结构化数据。

使用场景	能力点
作品下载	抖音视频 / 图集 / 实况 / 动图、最高画质；TikTok 视频原画 / 图集；音乐与动态 / 静态封面
账号维度	抖音发布 / 喜欢 / 收藏 / 收藏夹批量下载；TikTok 发布 / 喜欢作品；多账号批量
链接维度	批量下载链接作品；后台监听剪贴板链接自动下载
直播录制	获取抖音 / TikTok 直播拉流地址，调用 ffmpeg 录制直播
数据采集	作品评论、合集 / 合辑、账号详细数据、综合 / 视频 / 用户 / 直播四类搜索、抖音热榜
工程能力	增量下载、断点续传、多线程、自动跳过已下载、CSV/XLSX/SQLite 持久化、代理请求、Web API 服务化

⚠️ 以下功能在 README 中明确标注「弃用 / 失效 / 重构中」，使用当前版本时请勿依赖：

功能	状态	原因
Web UI 交互模式	重构中	代码尚未更新，菜单仅提示「该功能正在重构」，见 TikTokDownloader.py 的disable_function（约第 138-145 行）
内置加密参数算法	已过期失效、不再维护	为合规不再维护 xBogus / aBogus 等内置算法，部分功能可能无法正常工作，需自行准备生成代码
从浏览器读取 Cookie	已弃用	README 删除线标注，对应代码已注释（TikTokDownloader.py 约第 469-484 行）
扫码登录获取 Cookie	已失效	README 删除线标注，主菜单对应代码已注释

二、最小上手路径：环境、安装与首次下载

环境硬指标只有一条：Python 不低于 3.12。Windows 10 及以上、macOS、Linux 均可，README 推荐 Windows 11 自带终端以获得最佳交互体验。

获取源码后，pip 与 uv 两条等价路径任选其一：

git clone https://gitcode.com/GitHub_Trending/ti/TikTokDownloader cd TikTokDownloader python -m venv venv # 可选 pip install -r requirements.txt python main.py

cd TikTokDownloader uv sync --no-dev # uv 路径（README 推荐） uv run main.py

依赖清单（requirements.txt）即技术栈本身：httpx异步请求、rich彩色终端、fastapi/uvicorn服务化、pydantic数据校验、aiosqlite/openpyxl持久化。

Cookie 写入：核心前置条件

💡 Cookie（浏览器端身份凭证）决定接口权限与视频画质，仅在失效后需要重新写入。获取步骤参考 Cookie获取教程.md：浏览器访问抖音网页版，按 F12 打开开发人员工具，「网络」选项卡勾选「保留日志」，筛选框输入cookie-name:odin_tt，点击任意作品评论区后选取一个请求，复制Cookie的完整值。

3 分钟跑通首次下载

程序入口是 main.py：创建TikTokDownloader实例并调用run()。按以下步骤操作：

1. 看到项目标题与免责声明 → 输入YES确认（该选择持久化，仅首次出现）；
2. 主菜单选择手动输入 Cookie (抖音)→ 粘贴 Cookie 回车（或选从剪贴板读取 Cookie，复制后直接回车）；
3. 返回主菜单 → 选择终端交互模式；
4. 选择批量下载链接作品(抖音)→手动输入待采集的作品链接；
5. 粘贴一个抖音作品链接回车，等待进度条走完，文件落在root/folder_name目录下；
6. 任意菜单直接回车返回上级，输入Q或q结束程序。

最小可运行示例（写入 Cookie 后）：

python main.py # 终端交互模式 -> 批量下载链接作品(抖音) # -> 手动输入待采集的作品链接 -> 粘贴作品链接回车 # 产物出现在 Download/ 目录，文件名含创建时间、账号昵称、作品描述

三、settings.json 关键参数精讲

程序首次启动会在项目根目录自动生成settings.json，生成逻辑见 settings.py 的__create（约第 151-162 行），全部默认值定义在Settings.default（约第 21-121 行）。只挑真正影响行为的少数参数：

• cookie / cookie_tiktok：默认""。抖音 / TikTok 身份凭证，支持字符串或字典两种写法。__check_cookie（parameter.py 约第 280-287 行）同时接受两种类型，非法类型记警告并返回空值。未登录时账号页、私密账号作品等接口会直接失败；画质偏低时优先怀疑它。
• root：默认""。储存根路径。__check_root（约第 368-382 行）先判目录是否存在，再尝试在父目录下创建，都不行才回退项目根路径并写警告日志。填已存在的目录最省心。
• name_format：默认"create_time type nickname desc"。作品文件命名模板。__check_name_format（约第 404-415 行）要求每个键都在NAME_KEYS七键内（id/desc/create_time/nickname/uid/mark/type，见第 55-63 行），任一非法即整体回退默认组合。
• max_pages：默认0（等价 99999）。分页请求次数上限。__check_max_pages（约第 525-535 行）将0与非正整数统一按 99999 处理。喜欢 / 收藏接口只返回发布日期而非操作日期，程序必须拉全量再筛选，此参数是唯一的量级阀门。
• proxy / proxy_tiktok：默认""。平台代理地址。__check_proxy（约第 453-502 行）启动时实际请求平台页面测连，超时或报错直接返回None，代理静默失效，日志里找「代理测试成功 / 失败」确认。
• storage_format：默认""。数据持久化格式，可选csv/xlsx/sql（SQLite），映射见 manager.py 的DataLogger（约第 611-616 行）。__check_storage_format（约第 545-559 行）对非法值回退空值并警告。纯采集不下文件的场景必须配置此项，否则数据不落盘。

其余两个值得知道的：timeout（默认 10 秒，允许范围 2-10）与max_retry（默认 5 次，范围 0-5），校验分别在__check_timeout（约第 537-543 行）与__check_max_retry（约第 517-523 行）。旧版本字段有自动映射（settings.pyrename_params，约第 122-143 行）：default_mode→run_command、update_cookie→douyin_platform、original_cover→static_cover。

🔧 配置修改后需重启程序才生效，不支持热加载。

四、进阶用法：Docker 容器与 Web API 服务化

Docker 一行起容器

镜像有三种获取方式：用仓库根目录 Dockerfile 本地构建（双阶段构建，构建器python:3.12-bullseye编译依赖，最终镜像python:3.12-slim，EXPOSE 5555、VOLUME /app/Volume）；docker pull joeanamier/tiktok-downloader；docker pull ghcr.io/joeanamier/tiktok-downloader。

docker run --name <容器名称> -p <主机端口>:5555 \ -v tiktok_downloader_volume:/app/Volume -it <镜像名称> docker start -i <容器名称>

<镜像名称>需与第一步拉取的镜像名一致，如joeanamier/tiktok-downloader。容器内无法访问宿主机文件系统与本地浏览器，从浏览器读取 Cookie等依赖宿主环境的功能不可用（README 明确说明）。

Web API 接口模式

主菜单选择Web API 模式，程序在0.0.0.0:5555启动 FastAPI 服务，常量定义于 static.py（SERVER_HOST/SERVER_PORT，约第 9-13 行），服务实现见 main_server.py 的APIServer.run_server（约第 82-101 行）。访问http://127.0.0.1:5555/docs或/redoc可查阅自动生成的交互文档。

鉴权机制：每个接口经token_dependency（main_server.py 约第 46-51 行）读取请求头中的token，交由 function.py 的is_valid_token()（第 73 行）校验，失败返回HTTP 403。项目默认无需令牌；公开部署时建议在该函数处设置固定令牌防恶意请求，并可用/token接口测试有效性。

from httpx import post data = {"detail_id": "0123456789", "pages": 2} headers = {"token": ""} resp = post("http://127.0.0.1:5555/douyin/comment", json=data, headers=headers) print(resp.json())

🔧 生产化各一句：多实例请复制整个项目文件夹隔离运行；对外暴露前挂一层反向代理终结 TLS 并做限流；长期运行将 uvicorn 日志重定向到文件落盘。无人值守场景可在settings.json的run_command配置启动时预执行的功能指令，免去重复选菜单（校验逻辑见 parameter.py 的__check_run_command，约第 561-563 行）。

五、源码导读：一条链路串起五个模块

完整链路一句话串起：用户输入经 link/extractor.py 解析短链为完整链接，interface/ 下各接口类发起分页请求，extract/extractor.py 统一提取字段，downloader/ 先写入临时文件夹再移动到储存文件夹，storage/ 按storage_format持久化数据，调度中枢是 TikTokDownloader.py 的主菜单分发与run_command直达。

三个核心模块：

• 调度层TikTokDownloader（src/application/TikTokDownloader.py）：负责菜单分发、Cookie 写入、版本检查（run约第 430 行），另开守护线程periodic_update_params（约第 439-460 行），以COOKIE_UPDATE_INTERVAL = 15 * 60秒（static.py 第 16 行）为周期自动刷新 msToken、tt_wid 并回写 Cookie，因此长运行无需手动更新凭证。
• 接口层API模板（src/interface/template.py）：统一generate_params/request_data/check_response三段式（约第 95、248、221 行），子类 account.py、detail.py、comment.py、live.py、search.py 各自只关心 URL 与游标规则；终端菜单的 15 个功能入口定义在 main_terminal.py 的__function（约第 141-209 行）。
• 下载层Downloader（src/downloader/download.py）：semaphore = Semaphore(MAX_WORKERS)限制并发（MAX_WORKERS = 4，static.py 第 2 行）；__update_headers_range（约第 938-949 行）根据临时文件已有字节数注入Range: bytes=<position>-实现断点续传；request_file（约第 584 行）先落临时目录，完成后save_file移入目标目录。

两个值得读的工程细节：

• 重试与退避：retry.py 的Retry.retry装饰器按max_retry上限循环重试，每次失败后await wait()智能延时（随机延时见 function.py 第 20 行），失败达上限才终止任务（第 10-23 行）。
• 文件完整性校验：static.py 的FILE_SIGNATURES（第 29-57 行）内置 jpg / png / mp4 / mov 等文件头魔数，下载后据此校验真实类型并纠正后缀，避免「下载成功但内容损坏」的假成功。

六、避坑清单：高频现象与解法

现象	原因	解法
数据获取失败、视频清晰度偏低	Cookie 失效或未登录	重新写入 Cookie；私密账号需登录且已关注该账号的 Cookie
文件没出现在预期目录	root为非法路径，已回退项目根目录	查运行日志中 root 警告，改为已存在目录后重启
代理配置了却没生效	启动时代理测连失败，程序自动忽略	先手动验证代理可用，再确认日志出现「代理测试成功」
批量喜欢 / 收藏作品很慢	接口只返回发布日期，需拉全量再按日期筛选	用max_pages控制请求页数，缩小日期区间
升级后旧作品「丢失」	旧版本数据在_internal/Volume，新版未继承	按 README 更新方案一，将旧版_internal/Volume复制到新版_internal
多开实例行为异常	项目未针对多开优化	复制整个项目文件夹，各开独立实例

🔧 通用操作注意：终止程序或 ffmpeg 一律按Ctrl + C，不要直接点终端关闭按钮；批量收藏作品模式仅支持当前登录账号，暂不支持多账号；本项目不支持付费作品下载。

DouK-Downloader 适用于个人作品归档、中小规模账号数据采集与 Web API 服务化集成三类场景，双平台能力完整且全部逻辑可读可改。合规提示：本项目使用必须自行遵守相关法律法规与平台规则，因数据采集与下载行为产生的一切法律责任由使用者自行承担。

【免费下载链接】TikTokDownloader抖音 / TikTok 平台作品下载/数据采集工具项目地址: https://gitcode.com/GitHub_Trending/ti/TikTokDownloader