# 抖音视频下载小白图文手册

> 适用人群：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)