xhs-note-extractor 0.1.11
A Python package for extracting Xiaohongshu (Little Red Book) note data from URLs
License: MIT
Requires Python: >=3.12
Keywords: xiaohongshu, little-red-book, web-scraping, automation, uiautomator

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

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

## 功能特性

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

## 安装

### 基础安装

```bash
# 克隆仓库
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. **连接设备**
   ```bash
   # 检查设备连接
   adb devices
   ```

4. **安装依赖**
   ```bash
   pip install xhs-note-extractor[android]
   ```

### iOS 设备设置

#### 前置要求
- Python 3.7+
- iOS 设备
- macOS/Linux 系统
- 已越狱的 iOS 设备或能够运行 WebDriverAgent 的设备

#### 设置步骤

1. **安装系统工具**
   ```bash
   # macOS
   brew install libimobiledevice
   
   # Linux
   sudo apt-get install libimobiledevice-utils
   ```

2. **安装 WebDriverAgent**
   - 参考 [WebDriverAgent 官方文档](https://github.com/appium/WebDriverAgent)
   - 在 iOS 设备上启动 WDA 服务（默认端口 8100）

3. **配置端口转发**
   ```bash
   # 方法1: 使用 tidevice（推荐）
   pip install tidevice
   tidevice wdaproxy -B com.facebook.WebDriverAgentRunner.xctrunner
   
   # 方法2: 使用 iproxy
   iproxy 8100 8100
   ```

4. **安装 Python 依赖**
   ```bash
   pip install xhs-note-extractor[ios]
   ```

5. **验证连接**
   ```bash
   # 检查 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` 命令：

```bash
# 提取笔记并输出到控制台（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
```

### 编程接口

#### 推荐方式：跨平台提取器

```python
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专用（已废弃）

```python
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)
```

#### 指定平台

```python
# 仅使用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)
```

## 输出数据结构

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

```json
{
  "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设备。详细设置请参考上方的[平台支持](#平台支持)章节。

### 快速检查

```bash
# 检查Android设备
adb devices

# 检查iOS设备
idevice_id -l
```

## 故障排除

### 设备连接问题

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

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

### 权限问题

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

```bash
sudo adb kill-server
sudo adb start-server
```

## 示例

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

```bash
# 运行示例
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
```

### 运行测试

```bash
# 运行示例
python examples/basic_usage.py

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

## 注意事项

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

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！