开发了个抖音资源下载CLI工具,思路笔记(含源码分享)

1. 我最开始对这个需求的理解

1. 用户给一个抖音分享链接

2. 脚本请求一下

3. 拿到视频地址

4. 下载完事

• 一整段抖音分享文案

• 中间夹着一个 v.douyin.com 的短链

• 短链跳转之后，页面也不一定直接带完整作品信息

• 页面里的资源不只有视频，还有音频、封面、头像、图片

如何从真实世界里的抖音分享文案出发，稳定定位到目标作品，再把页面里的各种资源提取出来，并按需下载。

2. 当前这个项目已经做到什么程度了

当前已经成功实现的能力

1. 从一整段分享文案中提取短链接

2. 解析短链接跳转，拿到真实作品页

3. 提取目标作品 aweme_id

4. 尝试多个候选页面来源

5. 从页面结构化数据里匹配目标作品对象

6. 提取候选资源

7. 按资源类型下载到本地

当前已经验证成功的资源类型

• 视频 video

• 音频 audio

• 封面 cover

• 头像 avatar

• 图片 image

• 全部资源 all

这件事为什么让我觉得它已经“可用了”

• 手机 APP 里的分享链接

• 电脑浏览器里的分享链接

• 真实浏览器导出的 Cookie

3. 我在这个过程中真正学到的关键点

3.1 分享链接不是资源链接

3.2 真实作品页不一定有完整数据

• 既然已经跳到 https://www.douyin.com/video/{id}

• 那这个页面里肯定有完整作品详情

• 路由参数

• 一部分壳页面

• 甚至没有目标作品详情对象

3.3 页面里真正有价值的东西通常在 script 里

• awemeId

• groupId

• authorInfo

• video

• playAddr

• coverUrlList

3.4 不做目标匹配，拿到的数据很可能是错的

• 当前作品

• 推荐作品

• 相关推荐

• 其他资源块

3.5 “只下载视频”这个思路太窄了

• 找到视频链接

• 选一个最像 mp4 的

• 下载

头像、图片、音频等也应该能下载，而且要能选择下载，不是只下载视频。

资源分类器 + 按类型下载器

4. 我最后采用的整体方案

先把“作品定位”做好，再把“资源分类”做好，最后才谈下载。

整体流程

为什么我觉得这个流程是对的

• 页面变了也有 fallback

• script 容器变了也还有其他候选

• 资源类型变了也有分类逻辑

5. 完整技术栈（结合我为什么这么选）

5.1 运行环境

• Windows

• Python 3.12.10

• venv 虚拟环境

5.2 第三方依赖

curl_cffi

• 抖音网页对浏览器行为敏感

• 普通请求方式不一定稳定

• curl_cffi 能模拟更像浏览器的请求行为

• 跳转短链接

• 抓页面 HTML

• 下载资源文件

tenacity

typer

• 写法清晰

• 参数定义方便

• 帮助信息直观

pytest

• URL 提取

• aweme_id 提取

• 页面结构化数据解析

• 资源分类

• 资源优选

5.3 标准库

• re：正则提取与规则匹配

• json：解析结构化数据

• urllib.parse：处理 URL 和 unquote

• html：做 HTML 实体解码

• pathlib：管理本地文件路径

• dataclasses：数据模型

• logging：日志

• typing / collections.abc：类型标注

5.4 我为什么觉得这套技术栈够用

1. 依赖少

2. 每个库职责清晰

3. 适合快速试错与真实调试

4. 目前没有过度设计

6. 代码结构我是怎么理解的

6.1 请求层：client.py

• 创建浏览器风格 Session

• 注入 Cookie

• 跳转短链

• 抓页面 HTML

先把“像浏览器一样请求页面”这件事做好。

6.2 解析层：parser.py

• 从文案里提取 URL

• 从 URL 里提取 aweme_id

• 从 HTML 里提取 JSON

• 匹配目标作品对象

• 提取候选资源

在结构不稳定的真实网页里，怎么尽可能稳定地拿到目标作品的数据。

6.3 流程层：service.py

• 请求

• 解析

• 资源选择

• 下载

6.4 下载层：downloader.py

• 资源分类

• 资源优选

• 文件命名

• 文件下载

7. 我是怎么处理页面结构不稳定这件事的

我最开始踩到的坑

• video/{id} 页应该就能直接解析出详情

• 只有路由参数

• 没有完整作品对象

• 或者状态不完整

1. 真实作品页 URL

2. discover?modal_id={aweme_id}

3. iesdouyin/share/video/{aweme_id}

RENDER_DATA 为什么成为主战场

1. 找 script

2. 提内容

3. 解码

4. 解析 JSON

5. 匹配目标作品

8. 资源分类这件事，我最后是怎么收敛的

视频相关

• direct_mp4

• play_api

• dash_video

• unknown_video

非视频资源

• audio

• cover

• avatar

• image

为什么视频优先选 direct_mp4

1. direct_mp4

2. play_api

3. dash_video

4. unknown_video

为什么 all 模式不下载所有候选 URL

• 大量重复

• 资源混乱

• 用户根本不知道哪个有用

• 一个最佳视频

• 一个音频

• 一个封面

• 一个头像

9. 当前 CLI 是怎么组织的

resolve

• 解析分享文案

• 输出真实 URL 和 aweme_id

inspect

• 抓元数据

• 看资源分组

• 看视频优选结果

debug-page

• 看某个页面是否命中关键标记：
• RENDER_DATA
• playAddr
• awemeId
• authorInfo

download

• 按类型下载资源

10. 真实验证这件事为什么很重要

代码写出来了，看起来也合理，但其实没有在真实场景里跑过。

• 手机 APP 分享链接

• 浏览器分享链接

• 浏览器 Cookie

• 视频下载

• 音频下载

• 封面下载

• 头像下载

• all 模式下载

11. 当前我认为最容易失效的地方

1. 页面里的 RENDER_DATA 结构变了

2. 候选页面策略失效了

3. Cookie 不再能让页面返回完整状态

4. 资源 URL 规则变了

1. resolve 是否还能拿到真实作品页

2. aweme_id 是否还对

3. debug-page 是否还能看到关键标记

4. inspect 是否还能命中目标作品

5. 资源分组是否还合理

12. 当前已知局限

1. 仍然依赖有效 Cookie

2. 当前候选资源主要来自页面状态，不是完整官方详情接口体系

3. 图集类作品还没有单独建模

4. image 目前主要来自封面和页面图片候选，不等于完整图集下载

5. 还没有做批量任务

13. 当前最常用的命令

解析链接

查看资源信息

下载视频

下载音频

下载封面

下载头像

下载全部资源