---

📋 功能总览

模块	能力	状态
笔记采集	单笔记详情、批量笔记、笔记评论、相关推荐	✅
搜索能力	笔记搜索、用户搜索、热搜词、搜索建议、多排序/筛选	✅
用户画像	用户信息、用户笔记列表、用户全量笔记采集	✅
创作者中心	笔记发布（图文/视频）、数据分析、粉丝分析	✅
蒲公英平台	KOL搜索、博主详情、粉丝画像、合作邀请	✅
千帆平台	直播间KOL搜索、博主详情	✅
登录方式	二维码扫码、手机验证码、Cookie注入、创作者登录	✅
数据导出	Excel (.xlsx)、CSV (.csv)、JSON (.json)	✅
媒体下载	图片下载、视频下载、批量下载	✅
Cookie管理	多Cookie池、轮转、文件持久化	✅
命令行	笔记/搜索/用户/导出 CLI 工具	✅
异步支持	aiohttp 异步客户端	✅

---

🚀 快速开始

安装

# 1. 克隆项目
git clone https://github.com/your-org/xhs-sdk.git
cd xhs-sdk

# 2. 安装依赖
pip install -r requirements.txt

# 3. 下载签名 JS 文件（必需）
# 从 https://github.com/cv-cat/Spider_XHS/tree/master/static 下载以下文件到 static/ 目录：
#   - xhs_main_260411.js    (核心签名算法)
#   - xhs_a1.js             (A1 cookie生成)
#   - xhs_a1_other.js       (A1 备用)
#   - xhs_xray.js           (Xray-TraceID)
#   - xhs_rap.js            (RAP参数)
#   - xhs_creator_sign.js   (创作者签名)
#   - xhs_creator_260411.js (创作者算法)
#   - xhs_creator_sign_other.js (创作者备用)

配置

创建 .env 文件：

COOKIES='your_cookies_here'
LOG_LEVEL=INFO
REQUEST_TIMEOUT=15

或者在代码中直接传入：

from xhs_sdk.client import XHSClient  # 推荐：惰性加载
# 或 import xhs_sdk; client = xhs_sdk.XHSClient(...)

client = XHSClient(cookies="your_cookies_here")

获取 Cookie

1. 打开浏览器访问 小红书 并登录
2. 按 F12 打开开发者工具 → 控制台
3. 输入 document.cookie 并回车
4. 复制输出的字符串

---

📖 使用指南

初始化

from xhs_sdk import XHSClient

# 方式一: 直接传入 Cookie
client = XHSClient(cookies="a1=xxx; webId=yyy; ...")

# 方式二: 使用 .env 文件
client = XHSClient()

# 方式三: 使用上下文管理器（推荐）
with XHSClient() as client:
    # 在此使用 client
    pass

笔记操作

# 获取笔记详情
note = client.note.get("660000000000000001")

# 通过 URL 获取
note = client.note.get_detail_by_url(
    "https://www.xiaohongshu.com/explore/660000000000000001"
)

# 获取笔记评论
comments = client.note.get_comments("660000000000000001")
for comment in comments.get("comments", []):
    print(comment.get("content", ""))

# 获取全部评论（自动翻页）
all_comments = client.note.get_all_comments("660000000000000001", max_comments=500)

# 获取相关推荐
related = client.note.get_related("660000000000000001")

# 获取首页推荐
recommends = client.note.get_recommend(page_size=30)

搜索功能

from xhs_sdk.api.search import SearchAPI

# 基础搜索
results = client.search.notes(
    keyword="护肤",
    page=1,
    page_size=20,
    sort_type=SearchAPI.SORT_POPULAR,   # 按热度排序
    note_type=SearchAPI.NOTE_VIDEO,     # 只看视频
)

# 搜索所有结果（自动翻页）
all_notes = client.search.notes_all(
    keyword="美食",
    max_results=100,
    sort_type=SearchAPI.SORT_TIME,      # 按最新
    time_range=SearchAPI.TIME_ONE_WEEK, # 一周内
)

# 搜索用户
users = client.search.users("美食博主")

# 热搜词
hot = client.search.hot_keywords()

# 搜索建议
suggestions = client.search.suggest("护肤")

用户操作

# 获取用户信息
info = client.user.get_info("user_id_here")
print(f"昵称: {info['nickname']}, 粉丝: {info['fans']}")

# 获取用户笔记列表
notes = client.user.get_notes("user_id_here", page=1)

# 获取用户全部笔记（自动翻页）
all_notes = client.user.get_all_notes("user_id_here", max_notes=200)

数据导出

# 导出为 Excel
client.export(results, "output.xlsx")

# 导出为 CSV
client.export(results, "output.csv")

# 导出为 JSON
client.export(results, "output.json")

# 自定义字段映射
client.export(results, "output.xlsx", field_mapping={
    "note_id": "笔记ID",
    "title": "标题",
    "likes": "点赞数",
})

媒体下载

# 下载笔记中的图片和视频
note = client.note.get("660000000000000001")
result = client.download_note(note, "./downloads")
print(f"图片: {len(result['images'])} 张, 视频: {result['video']}")

# 仅下载图片
client.downloader.download_note_images(note, "./downloads")

# 仅下载视频
client.downloader.download_note_video(note, "./downloads")

登录

from xhs_sdk import XHSClient
from xhs_sdk.auth.login import LoginManager

# 二维码登录
manager = LoginManager()
cookies_str = manager.qrcode_login(show_in_terminal=True)

# 手机号登录
cookies_str = manager.phone_login()

# 创作者中心扫码登录
cookies_str = manager.creator_qrcode_login()

创作者中心

# 发布图文笔记
result = client.creator.post_note({
    "title": "我的第一篇笔记",
    "desc": "这是用 XHS-SDK 发布的",
    "type": 0,  # 0=公开
    "media_type": "image",
    "topics": ["日常", "生活"],
    "images": [open("image.jpg", "rb").read()],
})

# 发布视频笔记
result = client.creator.post_note({
    "title": "视频标题",
    "desc": "视频描述",
    "media_type": "video",
    "video": open("video.mp4", "rb").read(),
})

# 数据分析
stats = client.creator.get_self_note_stats()
fans = client.creator.get_fan_analysis()

蒲公英平台

# 获取分类
cats = client.pugongying.get_all_categories()

# 搜索KOL
users = client.pugongying.get_some_user(
    page=1,
    brand_user_id="your_brand_id",
)

# 获取博主详情
detail = client.pugongying.get_user_detail("user_id")
fans = client.pugongying.get_user_fans_detail("user_id")

命令行工具

# 查看配置
python -m xhs_sdk.cli.main config

# 搜索笔记
python -m xhs_sdk.cli.main search 护肤 --max 50 --sort popular --output 护肤笔记.xlsx

# 获取笔记详情
python -m xhs_sdk.cli.main note 660000000000000001

# 获取用户信息
python -m xhs_sdk.cli.main user user_id_here

---

🏗 项目架构

xhs-sdk/
├── xhs_sdk/
│   ├── __init__.py          # 导出入口
│   ├── client.py            # XHSClient / AsyncXHSClient
│   ├── exceptions.py        # 异常体系
│   ├── auth/
│   │   ├── signer.py        # 签名引擎（X-s/X-t/X-s-common）
│   │   └── login.py         # 登录管理
│   ├── api/
│   │   ├── note.py          # 笔记 API
│   │   ├── user.py          # 用户 API
│   │   ├── search.py        # 搜索 API
│   │   ├── creator.py       # 创作者中心 API
│   │   ├── pugongying.py    # 蒲公英平台 API
│   │   ├── qianfan.py       # 千帆平台 API
│   │   └── login.py         # 登录 API
│   ├── utils/
│   │   ├── http.py          # HTTP 客户端
│   │   ├── cookie.py        # Cookie 管理
│   │   ├── downloader.py    # 媒体下载
│   │   ├── exporter.py      # 数据导出
│   │   └── common.py        # 通用工具
│   └── cli/
│       └── main.py          # 命令行工具
├── static/                  # JS 签名文件（需下载）
├── examples/
│   └── basic_usage.py       # 使用示例
├── .env                     # 配置文件
├── requirements.txt
├── pyproject.toml
└── README.md

---

⚠️ 注意事项

1. 签名 JS 文件：需要从原项目下载 JS 文件放到 static/ 目录
2. Cookie 时效：Cookie 有效期通常为数天至数周，过期后需重新登录
3. 请求频率：建议控制请求频率避免触发反爬机制（推荐 1-2 QPS）
4. 法律合规：请遵守小红书用户协议和相关法律法规，仅采集公开数据
5. IP 限制：高频请求建议使用代理 IP 池

---

📄 许可证

基于 MIT 许可证开源。本 SDK 基于 Spider_XHS 的代码和架构封装重构。

---

⭐ Star & Follow

如果这个项目对你有帮助，请给个 Star ⭐ 支持！