xiaohongshu-scraper

# 小红书内容爬取 基于 XHS-Downloader 的小红书笔记抓取工具。 ## 快速使用 ### 1. 启动 API 服务（首次使用或服务未运行时） ```bash cd /Users/lixiaoji/clawd/skills/xiaohongshu-scraper/scripts ./xhs-api-service.sh start ``` ### 2. 完整抓取并保存（推荐） ```bash # 抓取笔记，下载图片，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/分享码`（短链接） - 支持一次输入多个链接，空格分隔 ## 服务管理 ```bash # 启动服务 ./xhs-api-service.sh start # 停止服务 ./xhs-api-service.sh stop # 重启服务 ./xhs-api-service.sh restart # 查看状态 ./xhs-api-service.sh status ``` ## API 直接调用 服务运行后，可以直接调用 API： ```bash # 获取笔记信息 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 格式 ```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 调用示例 ```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_scraper.py` | 完整抓取工具（推荐）：下载+OCR+保存 | | `xhs_api_client.py` | 简单客户端：仅获取信息 | | `xhs-api-service.sh` | API 服务管理脚本 | | `xhs_download.py` | 直接调用源码下载（无需 API） | ## 依赖 - XHS-Downloader（已安装在 `/Users/lixiaoji/Downloads/XHS-Downloader-master-2`） - Python 3.12+ - requests ## 配置路径 | 项目 | 路径 | |------|------| | XHS-Downloader 源码 | `/Users/lixiaoji/Downloads/XHS-Downloader-master-2` | | 默认下载目录 | `/Users/lixiaoji/Downloads/XHS-Downloader_V2/_internal/Volume/Download` | | 默认输出目录 | `/Users/lixiaoji/clawd/data/xhs` | | API 日志 | `/tmp/xhs-downloader-api.log` | ## 注意事项 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. 手动启动测试： ```bash cd /Users/lixiaoji/Downloads/XHS-Downloader-master-2 source venv/bin/activate python main.py api ``` ### 获取数据失败 1. 检查链接格式是否正确 2. 某些笔记可能有访问限制（作者设置、被删除等） 3. 尝试在浏览器中打开链接确认笔记是否可访问 ### 找不到下载的文件 1. 检查下载目录是否有新文件 2. 文件名格式为：`发布时间_作者昵称_标题_序号.扩展名` 3. 等待下载完成后再查找