# xhs_video_crawler

用于探索和研究小红书视频公开内容抓取流程的项目。

## 当前能力

第一版采用和抖音参考项目类似的两步式工作流：

1. `login_xhs.py` 启动一个可见 Chrome，并打开小红书发现页。
2. 你在 Chrome 中手动登录和处理验证码。
3. `XHS.py` 附着到这个 Chrome，监听页面已经收到的 `feed` 响应，提取其中的 mp4 视频地址并下载。

## 项目目的

本项目用于学习和验证视频信息采集相关技术，包括请求分析、页面解析、数据结构整理、下载流程设计和后续自动化处理。

## 合规说明

请仅在合法、合规、授权的范围内使用本项目：

- 遵守小红书平台服务条款、robots 协议和相关法律法规。
- 不采集、存储或传播未授权的隐私信息。
- 不绕过平台访问控制、验证码、登录风控或反爬限制。
- 不将本项目用于批量侵权下载、商业化搬运或其他违规用途。

## 安装环境

```bash
cd /Users/wangshaoqing/Desktop/MiaoSi/Study/xhs_video_crawler
python3 -m venv .venv
source .venv/bin/activate
pip install requests DrissionPage
```

## 使用方法

### 步骤 1：启动 Chrome 并手动登录

如果你已经通过抖音项目启动了调试端口为 `9223` 的 Chrome，可以直接在那个 Chrome 里打开并登录小红书，不需要再运行 `login_xhs.py`。

如果还没有可复用的 Chrome，再运行：

```bash
./.venv/bin/python login_xhs.py
```

脚本会用默认端口 `9223` 打开 `https://www.xiaohongshu.com/explore`。请在打开的浏览器里完成登录；如果出现验证码，也需要手动处理。

### 步骤 2：下载发现页视频

登录完成后，保持 Chrome 不要关闭，执行：

```bash
./.venv/bin/python XHS.py --max-videos 10
```

常用参数：

```bash
# 指定下载数量
./.venv/bin/python XHS.py --max-videos 20

# 指定保存目录
./.venv/bin/python XHS.py --max-videos 10 --output-dir video

# 默认启用温和随机浏览节奏；可调整停留时间和阶段长休息
./.venv/bin/python XHS.py --max-videos 20 --min-wait 2 --max-wait 6 --long-break-every 4

# 测试时可以缩短等待；需要最快速度时可关闭 human mode
./.venv/bin/python XHS.py --max-videos 3 --min-wait 0.5 --max-wait 1
./.venv/bin/python XHS.py --max-videos 3 --no-human-mode

# 限制最长运行时间，单位秒
./.venv/bin/python XHS.py --max-videos 20 --max-runtime 600

# 长任务队列模式：适合下载大量视频，可中断后继续
./.venv/bin/python XHS.py \
  --source video-channel \
  --target-videos 1000 \
  --queue-file data/xhs_queue.jsonl \
  --max-runtime 7200

# 继续上次未完成的队列任务
./.venv/bin/python XHS.py --queue-file data/xhs_queue.jsonl --target-videos 1000

# 如果启动 Chrome 时换了端口，下载脚本也要使用同一个端口
./.venv/bin/python login_xhs.py --browser-port 9334
./.venv/bin/python XHS.py --browser-port 9334 --max-videos 10
```

下载文件默认保存到 `video/` 目录，文件名格式大致为：

```text
[作者]标题-note_id.mp4
```

## 工作原理

- 浏览器负责加载小红书页面和保留登录态。
- 脚本只监听浏览器里已经产生的网络响应。
- 解析器会递归查找响应 JSON 中的 `master_url`、`backup_urls` 等视频地址字段。
- 默认会在发现页和详情页之间随机停留、上下滚动，并在阶段下载后长停留。
- 下载过程会去重，并在单个视频失败时继续处理后续视频。
- 队列模式会把笔记链接和处理状态保存到 JSONL 文件，支持长任务恢复。

## 测试

```bash
python3 -m unittest test_xhs.py test_login_xhs.py -v
```

## 后续计划

- 分析公开视频页面的数据结构。
- 提取视频标题、作者、发布时间、封面和视频地址等元数据。
- 支持按链接或关键词进行探索性抓取。
- 保存抓取结果到本地文件或结构化数据表。
- 为后续下载、去重和任务队列处理预留接口。

## 免责声明

本项目仅用于技术学习与研究。使用者应自行承担使用本项目产生的全部责任。