xhs-note-extractor 0.1.8.dev8

A Python package for extracting Xiaohongshu (Little Red Book) note data from URLs

小红书笔记提取器 (Xiaohongshu Note Extractor)

一个用于从小红书提取笔记数据的Python工具，支持Android和iOS双平台，提供命令行界面和编程接口。

功能特性

• 🔍 从小红书笔记URL提取详细数据
• 📱 跨平台支持 - Android (uiautomator2) 和 iOS (facebook-wda)
• 📊 支持JSON和CSV输出格式
• 🖥️ 命令行界面支持
• 🔧 可配置的设备连接选项
• 🔄 自动设备检测和切换
• 🛡️ 优雅的错误处理和设备状态检查

安装

基础安装

# 克隆仓库
git clone <repository-url>
cd xhs-note-extractor

# 根据您的设备选择安装方式：

# Android 设备
pip install -e .[android]

# iOS 设备
pip install -e .[ios]

# 同时支持两个平台
pip install -e .[all]

# 仅安装核心库（开发模式）
pip install -e .

平台支持

Android 设备设置

前置要求

• Python 3.7+
• Android 设备
• ADB 工具

设置步骤

1. 启用开发者选项

   • 进入设置 → 关于手机
   • 连续点击"版本号"7次

2. 启用 USB 调试

   • 开发者选项 → 开启"USB调试"

3. 连接设备

   # 检查设备连接
   adb devices
   

4. 安装依赖

   pip install xhs-note-extractor[android]
   

iOS 设备设置

前置要求

• Python 3.7+
• iOS 设备
• macOS/Linux 系统
• 已越狱的 iOS 设备或能够运行 WebDriverAgent 的设备

设置步骤

1. 安装系统工具

   # macOS
   brew install libimobiledevice
   
   # Linux
   sudo apt-get install libimobiledevice-utils
   

2. 安装 WebDriverAgent

   • 参考 WebDriverAgent 官方文档
   • 在 iOS 设备上启动 WDA 服务（默认端口 8100）

3. 配置端口转发

   # 方法1: 使用 tidevice（推荐）
   pip install tidevice
   tidevice wdaproxy -B com.facebook.WebDriverAgentRunner.xctrunner
   
   # 方法2: 使用 iproxy
   iproxy 8100 8100
   

4. 安装 Python 依赖

   pip install xhs-note-extractor[ios]
   

5. 验证连接

   # 检查 iOS 设备
   idevice_id -l
   
   # 验证 WDA 状态
   curl http://localhost:8100/status
   

[!IMPORTANT] iOS连接问题排查:

• 确保WebDriverAgent已在设备上运行
• 确保端口转发已设置（iproxy 8100 8100）
• 访问 http://localhost:8100/status 应该返回JSON响应
• 如果看到"连接被拒绝"，检查WDA是否正在运行

使用方法

命令行界面（CLI）

安装完成后，可以直接使用 xhs-extract 命令：

# 提取笔记并输出到控制台（JSON格式）
xhs-extract https://www.xiaohongshu.com/explore/note_id

# 保存到文件
xhs-extract https://www.xiaohongshu.com/explore/note_id -o note_data.json

# 输出CSV格式
xhs-extract https://www.xiaohongshu.com/explore/note_id -f csv -o note_data.csv

# 启用详细输出模式
xhs-extract https://www.xiaohongshu.com/explore/note_id -v

# 查看帮助
xhs-extract --help

编程接口

推荐方式：跨平台提取器

from xhs_note_extractor import CrossPlatformXHSExtractor

# 创建跨平台提取器实例（自动检测设备）
extractor = CrossPlatformXHSExtractor()

# 自动连接可用设备（优先Android）
if extractor.connect_device():
    # 提取笔记数据
    note_data = extractor.extract_note_data("https://www.xiaohongshu.com/explore/note_id")
    
    print(f"作者: {note_data['author_name']}")
    print(f"点赞: {note_data['likes']}")
    print(f"内容: {note_data['content']}")
    print(f"图片数: {len(note_data['image_urls'])}")
else:
    print("未检测到可用设备")

旧方式：Android专用（已废弃）

from xhs_note_extractor import XHSNoteExtractor
import warnings

# 注意：此方式已被标记为废弃，将在v3.0.0移除
# 会收到 DeprecationWarning

with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    extractor = XHSNoteExtractor()
    
# 使用方法与CrossPlatformXHSExtractor相同
note_data = extractor.extract_note_data(url)

指定平台

# 仅使用iOS设备
extractor = CrossPlatformXHSExtractor()
ios_devices = extractor.available_devices['ios']
if ios_devices:
    extractor.connect_device(ios_devices[0])
    note_data = extractor.extract_note_data(url)

输出数据结构

提取的数据包含以下字段：

{
  "title": "笔记标题",
  "content": "笔记完整内容",
  "author": {
    "nickname": "作者昵称",
    "user_id": "用户ID"
  },
  "likes": 100,
  "collects": 50,
  "comments": 25,
  "shares": 10,
  "image_urls": [
    "图片URL1",
    "图片URL2"
  ],
  "video_url": "视频URL（如果有）",
  "tags": ["标签1", "标签2"],
  "publish_time": "发布时间",
  "note_id": "笔记ID"
}

设备连接

工具会自动检测并连接可用的Android和iOS设备。详细设置请参考上方的平台支持章节。

快速检查

# 检查Android设备
adb devices

# 检查iOS设备
idevice_id -l

故障排除

设备连接问题

如果CLI工具提示设备未连接：

1. 检查USB连接是否正常
2. 确认已在设备上启用USB调试
3. 确认已授权USB调试权限
4. 尝试重新插拔USB线缆
5. 重启ADB服务：

   adb kill-server
   adb start-server
   

权限问题

在Linux/Mac上，可能需要为ADB添加权限：

sudo adb kill-server
sudo adb start-server

示例

查看 examples/basic_usage.py 文件获取更多使用示例：

# 运行示例
python examples/basic_usage.py

开发

项目结构

xhs-note-extractor/
├── xhs_note_extractor/
│   ├── __init__.py
│   ├── cli.py          # 命令行界面
│   ├── extractor.py    # 核心提取器
│   └── utils.py        # 工具函数
├── examples/
│   └── basic_usage.py  # 使用示例
├── tests/
├── requirements.txt
├── setup.py
└── README.md

运行测试

# 运行示例
python examples/basic_usage.py

# 使用CLI工具
xhs-extract --help

注意事项

• 本工具仅供学习和研究使用
• 请遵守小红书的使用条款和API限制
• 过度频繁的请求可能导致IP被封禁
• 建议在合理范围内使用，避免对平台造成负担

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！