xiaohongshu-search 0.2.0

小红书搜索工具 - 企业级实现

小红书搜索工具

企业级小红书笔记搜索工具，基于 TikHub API 实现。

特性

• ✅ TikHub API 集成 - 稳定的小红书数据接口
• ✅ Cookie 池管理 - 支持从后端服务动态获取 Cookie
• ✅ 并发控制 - 多线程并发获取数据
• ✅ 限流保护 - 可配置请求间隔
• ✅ 统计信息 - 完整的耗时和成功率统计
• ✅ 数据导出 - JSON 和 Excel 格式
• ✅ 日志记录 - 详细的运行日志

安装

pip install xiaohongshu-search

可选依赖（导出 Excel）

pip install xiaohongshu-search[excel]

配置

1. 设置 TikHub API Key

export TIKHUB_API_KEY="your_api_key"

或创建 .env 文件：

TIKHUB_API_KEY=your_api_key

2. （可选）配置后端服务

如果需要 Cookie 池管理功能：

# .env
BACK_END_API_BASE_URL=https://ms.jr.jd.com
SOURCE=xiaohongshu

# 或者直接使用环境变量中的 Cookie
COOKIES=cookie1;cookie2;cookie3

使用

命令行

# 基本搜索
xhs-search "美食推荐"

# 搜索并导出 JSON
xhs-search "北京旅游" -o results.json

# 搜索并导出 Excel
xhs-search "护肤心得" --excel results.xlsx

# 自动翻页获取多页数据
xhs-search "穿搭" -n 5 -o all.json

# 并发模式（10 个工作线程）
xhs-search "数码评测" -n 10 -w 10 -o all.json

# 按点赞数排序
xhs-search "健身" --sort popularity_descending

# 只看视频笔记
xhs-search "教程" --type 视频笔记

# 只看最近一周
xhs-search "评测" --time 一周内

# 获取笔记详情（慢）
xhs-search "探店" --fetch-details -o with_details.json

# 显示详细信息
xhs-search "数码" -v

# 完整示例：并发搜索 + 导出 Excel
xhs-search "北京美食" -n 5 -w 5 --excel beijing_food.xlsx

Python API

from xiaohongshu_search.core.search_processor import SearchProcessor
from xiaohongshu_search.backend.cookie_manager import CookiePool

# 简单模式
processor = SearchProcessor(api_key="your_api_key")
notes = processor.search(keyword="美食推荐", max_pages=5)
processor.export_json("results.json")
processor.export_excel("results.xlsx")

# 高级模式（带 Cookie 池）
cookie_pool = CookiePool()
processor = SearchProcessor(
    api_key="your_api_key",
    cookie_pool=cookie_pool,
    max_workers=5,
    delay=0.5,
)
notes = processor.search(keyword="美食推荐")

# 获取笔记详情
note_ids = [n["note_id"] for n in notes]
details = processor.fetch_details(note_ids)

# 获取统计信息
stats = processor.get_stats()
print(f"找到 {stats.total_found} 篇笔记")
print(f"耗时 {stats.search_time:.2f}秒")

选项

选项	说明	默认值
-p, --page	页码	1
-n, --max-pages	最大页数（自动翻页）	1
-o, --output	输出 JSON 文件	-
--excel	输出 Excel 文件	-
--sort	排序方式	general
--type	笔记类型	不限
--time	时间筛选	不限
-w, --workers	并发工作线程数	1
-d, --delay	请求间隔（秒）	0.1
--fetch-details	获取笔记详情	false
-v, --verbose	显示详细信息	false

排序方式

• general - 综合排序
• time_descending - 最新
• popularity_descending - 最多点赞
• comment_descending - 最多评论
• collect_descending - 最多收藏

笔记类型

• 不限 - 所有类型
• 视频笔记 - 仅视频
• 普通笔记 - 仅图文
• 直播笔记 - 仅直播

时间筛选

• 不限 - 所有时间
• 一天内 - 24 小时内
• 一周内 - 7 天内
• 半年内 - 6 个月内

项目结构

xiaohongshu_search/
├── __init__.py           # 包初始化
├── main.py               # 命令行入口
├── core/
│   ├── __init__.py
│   └── search_processor.py  # 搜索处理器（核心业务逻辑）
├── backend/
│   ├── __init__.py
│   └── cookie_manager.py    # Cookie 池管理（后端交互）
└── utils/
    └── __init__.py

依赖

• Python 3.12+
• tikhub-xiaohongshu >= 0.1.1
• python-dotenv >= 1.1.1
• requests >= 2.31.0
• retrying >= 1.4.2

可选依赖（导出 Excel）：

• pandas >= 2.2.0
• openpyxl >= 3.0.0

日志

运行日志保存在 logs/ 目录下，文件名格式：xhs_search_YYYYMMDD_HHMMSS.log

与 xhs_review 的区别

特性	xhs_review	xiaohongshu_search
API 来源	原始 HTTP + 签名	TikHub API
Cookie 管理	复杂（后端 + 设备）	简化（后端 + 环境变量）
设备联动	支持（ADB）	不支持
并发控制	支持	支持
数据导出	支持	支持
依赖复杂度	高	低
使用场景	企业级采集	快速搜索/轻量采集

许可证

MIT

作者

叶浩