xiaohongshu-scraper（小红书刮刀）

小红书内容爬取

基于 XHS-Downloader 的小红书笔记抓取工具。

快速使用

1. 启动 API 服务（首次使用或服务未运行时）

cd /Users/lixiaoji/clawd/skills/xiaohongshu-scraper/scripts
./xhs-api-service.sh start

2. 完整抓取并保存（推荐）

# 抓取笔记，下载图片，OCR识别，保存到指定文件夹
python xhs_scraper.py "笔记URL" --output /tmp/xhs_note

# 批量抓取多个链接
python xhs_scraper.py "URL1" "URL2" "URL3" --output /tmp/xhs_notes

# 不进行 OCR（更快）
python xhs_scraper.py "笔记URL" --output /tmp/xhs_note --no-ocr

# 仅获取信息不下载
python xhs_scraper.py "笔记URL" --info-only

# 输出 JSON 格式
python xhs_scraper.py "笔记URL" --json

3. 支持的链接格式

• https://www.xiaohongshu.com/explore/作品ID?xsec_token=XXX
• https://www.xiaohongshu.com/discovery/item/作品ID?xsec_token=XXX
• https://www.xiaohongshu.com/user/profile/作者ID/作品ID?xsec_token=XXX
• https://xhslink.com/分享码（短链接）
• 支持一次输入多个链接，空格分隔

服务管理

# 启动服务
./xhs-api-service.sh start

# 停止服务
./xhs-api-service.sh stop

# 重启服务
./xhs-api-service.sh restart

# 查看状态
./xhs-api-service.sh status

API 直接调用

服务运行后，可以直接调用 API：

# 获取笔记信息
curl -X POST http://127.0.0.1:5556/xhs/detail \
  -H "Content-Type: application/json" \
  -d '{"url": "笔记链接", "download": true}'

API 文档：http://127.0.0.1:5556/docs

输出文件结构

output_dir/
├── 作品ID/
│   ├── note.json           # 结构化数据（完整信息）
│   ├── note.md             # Markdown 文档
│   ├── images/             # 下载的图片
│   │   ├── 01.jpeg
│   │   ├── 02.jpeg
│   │   └── ...
│   └── ocr/                # OCR 识别结果
│       ├── 01.md           # 每张图片对应的 OCR 文本
│       ├── 02.md
│       └── ...

note.json 格式

{
  "note_id": "笔记ID",
  "fetch_time": "抓取时间",
  "title": "标题",
  "desc": "描述/正文",
  "type": "作品类型（图文/视频）",
  "author": {
    "nickname": "作者昵称",
    "user_id": "作者ID",
    "profile_url": "作者主页"
  },
  "interact": {
    "liked_count": 123,
    "collected_count": 456,
    "comment_count": 78,
    "share_count": 9
  },
  "tags": ["标签1", "标签2"],
  "publish_time": "发布时间",
  "last_update_time": "最后更新时间",
  "url": "笔记链接",
  "download_urls": ["下载地址列表"],
  "local_files": ["本地文件路径"],
  "ocr_results": [
    {"image": "01.jpeg", "text": "OCR识别的文字"}
  ]
}

Python 调用示例

import subprocess
import json
from pathlib import Path

def scrape_xhs_note(url: str, output_dir: str) -> dict:
    """抓取小红书笔记"""
    script = "/Users/lixiaoji/clawd/skills/xiaohongshu-scraper/scripts/xhs_scraper.py"
    result = subprocess.run(
        ["python", script, url, "--output", output_dir, "--json"],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        return json.loads(result.stdout)
    else:
        raise Exception(result.stderr)

# 使用示例
data = scrape_xhs_note("https://www.xiaohongshu.com/explore/xxx", "/tmp/xhs")
print(data["title"])

脚本列表

依赖

• XHS-Downloader（已安装在 /Users/lixiaoji/Downloads/XHS-Downloader-master-2）
• Python 3.12+
• requests

配置路径

注意事项

1. 首次使用需要先启动 API 服务
2. 下载的文件默认保存在 XHS-Downloader 目录
3. 使用 --output 参数将文件整理保存到指定目录
4. OCR 功能使用 macOS 内置的 Vision 框架，仅支持 macOS
5. 某些笔记可能有访问限制（作者设置、被删除等）
6. 短链接需要网络请求解析，确保网络通畅

故障排除

API 服务无法启动

1. 检查端口 5556 是否被占用：lsof -i:5556
2. 查看日志：cat /tmp/xhs-downloader-api.log
3. 手动启动测试： cd /Users/lixiaoji/Downloads/XHS-Downloader-master-2 source venv/bin/activate python main.py api

获取数据失败

1. 检查链接格式是否正确
2. 某些笔记可能有访问限制（作者设置、被删除等）
3. 尝试在浏览器中打开链接确认笔记是否可访问

找不到下载的文件

1. 检查下载目录是否有新文件
2. 文件名格式为：发布时间_作者昵称_标题_序号.扩展名
3. 等待下载完成后再查找