xhs_video_crawler

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

当前能力

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

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

项目目的

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

合规说明

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

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

安装环境

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，再运行：

./.venv/bin/python login_xhs.py

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

步骤 2：下载发现页视频

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

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

常用参数：

# 指定下载数量
./.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

# 长任务队列模式：适合下载大量视频，可中断后继续
# video-channel 对应网页顶部“视频”频道，通常比关键词搜索更适合大量下载
./.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 \
  --source search \
  --keyword 猫咪 \
  --target-videos 100 \
  --queue-file data/search_cat_queue.jsonl

# 继续上次未完成的队列任务
./.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/ 目录，文件名格式大致为：

[作者]标题-note_id.mp4

工作原理

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

测试

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

后续计划

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

免责声明

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