330 lines
7.0 KiB
Markdown
330 lines
7.0 KiB
Markdown
# 抖音视频下载小白图文手册
|
||
|
||
> 适用人群：Mac 用户、项目已经在本地、不会代码也可以照着做。
|
||
|
||
## 这份手册能帮你做什么
|
||
|
||
照着这份手册执行，你可以完成下面这件事：
|
||
|
||
- 打开项目
|
||
- 安装运行所需环境
|
||
- 登录抖音
|
||
- 启动抓取
|
||
- 在本地找到下载好的 mp4 视频
|
||
|
||
## 你开始前要知道的事
|
||
|
||
这个项目不是“自动登录”的。
|
||
|
||
你需要自己在浏览器里完成：
|
||
|
||
- 登录抖音账号
|
||
- 验证码
|
||
|
||
脚本负责做的是：
|
||
|
||
- 打开浏览器
|
||
- 连接到浏览器
|
||
- 读取当前浏览器页面里的作品数据
|
||
- 下载视频文件
|
||
|
||
## 第 1 步：确认 Mac 上已经安装了 Python
|
||
|
||
打开“终端”应用。
|
||
|
||
在终端里输入下面的命令：
|
||
|
||
```bash
|
||
python3 --version
|
||
```
|
||
|
||
你应该看到类似这样的结果：
|
||
|
||
```text
|
||
Python 3.11.0
|
||
```
|
||
|
||
如果你看到了版本号，说明可以继续。
|
||
|
||
如果提示找不到 `python3`：
|
||
|
||
- 先安装 Python 3
|
||
- 安装完成后重新执行上面的命令
|
||
|
||
## 第 2 步：进入项目目录
|
||
|
||
假设你的项目放在桌面目录下，那么在终端里输入：
|
||
|
||
```bash
|
||
cd ~/Desktop/MiaoSi/Study/douyin-crawler-poc
|
||
```
|
||
|
||
你也可以把上面的路径换成你自己的项目路径。
|
||
|
||
然后输入：
|
||
|
||
```bash
|
||
pwd
|
||
```
|
||
|
||
如果输出结果里能看到 `douyin-crawler-poc`，说明你已经进入了正确目录。
|
||
|
||
## 第 3 步：创建虚拟环境
|
||
|
||
在项目目录里执行：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
```
|
||
|
||
这个命令的作用是：
|
||
|
||
- 给当前项目准备一个独立的 Python 运行环境
|
||
- 避免你的系统里其他 Python 包互相影响
|
||
|
||
如果这一步没有报错，就继续下一步。
|
||
|
||
## 第 4 步：激活虚拟环境
|
||
|
||
在终端里执行：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
成功后，你会看到终端左边通常多出一个类似 `.venv` 的提示。
|
||
|
||
如果你没有看到，也不用太紧张，只要命令没有报错，也通常可以继续。
|
||
|
||
## 第 5 步：安装依赖
|
||
|
||
在终端里执行：
|
||
|
||
```bash
|
||
pip install requests DrissionPage
|
||
```
|
||
|
||
如果安装成功，终端会显示若干 `Successfully installed` 或安装完成信息。
|
||
|
||
如果安装失败，常见处理方式：
|
||
|
||
- 检查网络是否可用
|
||
- 确认前一步虚拟环境已经激活
|
||
- 再执行一次命令
|
||
|
||
## 第 6 步：启动登录浏览器
|
||
|
||
在终端里执行：
|
||
|
||
```bash
|
||
./.venv/bin/python login_douyin.py
|
||
```
|
||
|
||
如果成功，你会看到类似提示：
|
||
|
||
```text
|
||
[INFO] Chrome 已启动。请在打开的浏览器中完成抖音登录和验证码。
|
||
```
|
||
|
||
这一步会做两件事：
|
||
|
||
- 打开一个新的 Chrome 浏览器窗口
|
||
- 给后面的抓取脚本准备调试端口
|
||
|
||
如果这一步失败，常见原因是：
|
||
|
||
- Chrome 没有安装
|
||
- 调试端口没能准备好
|
||
|
||
## 第 7 步：在浏览器里登录抖音
|
||
|
||
浏览器打开后，请你自己完成：
|
||
|
||
- 登录抖音账号
|
||
- 完成验证码
|
||
- 确认你已经进入想抓取的页面
|
||
|
||
这个页面可以是：
|
||
|
||
- 某个博主主页
|
||
- 某个单独视频页面
|
||
|
||
建议此时先不要关闭这个浏览器窗口。
|
||
|
||
## 第 8 步：运行抓取命令
|
||
|
||
回到终端，执行：
|
||
|
||
```bash
|
||
./.venv/bin/python Douyin.py
|
||
```
|
||
|
||
这条命令的意思是：
|
||
|
||
- 附着到刚才打开的浏览器
|
||
- 自动读取你当前打开的页面
|
||
- 如果当前页是博主主页，就下载当前已加载的视频
|
||
- 如果当前页是单视频页，就只下载这一条视频
|
||
|
||
如果自动判断失败，或者你不想切换浏览器页面，也可以手动传一个目标：
|
||
|
||
```bash
|
||
./.venv/bin/python Douyin.py "https://www.douyin.com/user/你的博主主页"
|
||
./.venv/bin/python Douyin.py "https://www.douyin.com/video/某个视频ID"
|
||
./.venv/bin/python Douyin.py "7619989983668240802"
|
||
```
|
||
|
||
## 第 9 步：判断是否抓取成功
|
||
|
||
抓取成功时，终端一般会看到类似输出：
|
||
|
||
```text
|
||
[INFO] 正在处理第 1 页
|
||
[OK] 已保存: video/某个视频标题-1234567890.mp4
|
||
[INFO] 处理结束，共下载 18 个视频。
|
||
```
|
||
|
||
如果你当前打开的是单视频页，也可能看到类似：
|
||
|
||
```text
|
||
[OK] 已保存: video/某个视频标题-1234567890.mp4
|
||
[INFO] 处理结束，共下载 1 个视频。
|
||
```
|
||
|
||
其中最关键的是：
|
||
|
||
- 出现 `[OK] 已保存`
|
||
- 最后一行出现 `处理结束`
|
||
|
||
如果看到这些内容，说明视频已经成功下载。
|
||
|
||
## 第 10 步：去本地查看下载好的视频
|
||
|
||
下载成功后，视频会保存在项目目录下的：
|
||
|
||
```text
|
||
video/
|
||
```
|
||
|
||
你可以用以下任一方式查看：
|
||
|
||
- 在 Finder 里打开项目目录，进入 `video/`
|
||
- 在 VS Code 左侧资源管理器中打开 `video/`
|
||
- 在终端里执行 `ls video`
|
||
|
||
视频文件格式是：
|
||
|
||
```text
|
||
.mp4
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 终端提示找不到 `python3`
|
||
|
||
说明你的 Mac 还没有安装可用的 Python 3。
|
||
|
||
先安装 Python 3，再重新执行：
|
||
|
||
```bash
|
||
python3 --version
|
||
```
|
||
|
||
### 2. 终端提示找不到 `.venv`
|
||
|
||
说明你还没有成功创建虚拟环境。
|
||
|
||
请先执行：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
```
|
||
|
||
然后再执行：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
### 3. 启动浏览器后提示调试端口未就绪
|
||
|
||
常见处理方法：
|
||
|
||
- 先确认 Chrome 已正常打开
|
||
- 不要立即关闭浏览器
|
||
- 重新运行 `login_douyin.py`
|
||
|
||
### 4. 运行抓取命令后提示无法连接浏览器
|
||
|
||
说明抓取脚本没有连上登录浏览器。
|
||
|
||
请按顺序重试：
|
||
|
||
1. 重新执行 `./.venv/bin/python login_douyin.py`
|
||
2. 确认浏览器保持打开
|
||
3. 再执行 `./.venv/bin/python Douyin.py`
|
||
|
||
### 5. 登录后还是没有下载出视频
|
||
|
||
可能原因：
|
||
|
||
- 你还没有真正登录成功
|
||
- 验证码还没完全通过
|
||
- 当前页面不是作品页
|
||
- 当前页面没有加载出作品数据
|
||
|
||
建议：
|
||
|
||
- 先确认浏览器里已经能正常看到博主主页和作品
|
||
- 再重新执行抓取命令
|
||
|
||
### 6. 我看不到 `video/` 文件夹
|
||
|
||
先在终端执行：
|
||
|
||
```bash
|
||
ls video
|
||
```
|
||
|
||
如果这里能看到很多 `.mp4` 文件，说明视频已经下载成功。
|
||
|
||
如果 VS Code 左侧看不到 `video/`，请刷新资源管理器。
|
||
|
||
## 建议你第一次就这样操作
|
||
|
||
把下面这几条命令按顺序执行：
|
||
|
||
```bash
|
||
cd ~/Desktop/MiaoSi/Study/douyin-crawler-poc
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install requests DrissionPage
|
||
./.venv/bin/python login_douyin.py
|
||
./.venv/bin/python Douyin.py
|
||
```
|
||
|
||
## 附：当前项目的实际工作方式
|
||
|
||
当前版本的逻辑是：
|
||
|
||
- 默认读取当前浏览器页面
|
||
- 如果当前页是博主主页，就监听该页面的作品列表接口
|
||
- 如果当前页是单视频页，就下载这一条视频
|
||
- 传入链接或 `aweme_id` 时，也可以按指定目标抓取
|
||
|
||
所以它更适合抓：
|
||
|
||
- 博主主页当前页面里已经能看到的作品
|
||
- 当前打开的单视频页面
|
||
|
||
而不是：
|
||
|
||
- 自动抓完整个博主所有历史视频
|
||
- 抓任意网页
|
||
|
||
## 进一步阅读
|
||
|
||
- [README 首页说明](/Users/wangshaoqing/Desktop/MiaoSi/Study/douyin-crawler-poc/README.md)
|
||
- [当前项目需求说明](/Users/wangshaoqing/Desktop/MiaoSi/Study/douyin-crawler-poc/externaldocs/2026-04-17-readme-and-beginner-guide-requirements.md)
|
||
- [定向抓取后续需求](/Users/wangshaoqing/Desktop/MiaoSi/Study/douyin-crawler-poc/externaldocs/2026-04-17-douyin-targeted-crawling-requirements.md)
|