1. xiaohongshu-cli项目概述

xiaohongshu-cli是一个通过逆向工程小红书API实现的命令行工具，它允许开发者直接在终端中完成小红书平台的各类操作。这个工具最初由开发者jackwener创建并维护，目前在GitHub上获得了超过2.3k的星标，显示出其在技术社区中的受欢迎程度。

作为一个Python开发的命令行工具，xiaohongshu-cli最大的价值在于它打破了常规需要通过网页或APP才能使用小红书的限制。开发者现在可以通过简单的命令行指令，就能完成从内容浏览到社交互动的完整流程。这对于需要批量处理小红书内容的开发者、数据分析师或是希望将小红书功能集成到自己应用中的技术人员来说，无疑提供了极大的便利。

工具的核心功能覆盖了小红书的各个方面：从基础的认证登录、内容搜索阅读，到复杂的社交互动和内容发布。特别值得一提的是，它还实现了反检测机制，通过模拟真实用户行为来降低被平台风控的风险。这种对技术细节的关注，使得xiaohongshu-cli在同类工具中脱颖而出。

2. 核心功能解析

2.1 认证与登录机制

xiaohongshu-cli提供了三种灵活的认证方式，每种方式都针对不同的使用场景进行了优化：

1. 浏览器Cookie提取：这是最便捷的登录方式。工具会自动检测系统中已安装的浏览器（支持Chrome、Firefox、Safari等主流浏览器），并从中提取有效的登录Cookie。这种方式无需重复输入账号密码，特别适合个人开发者日常使用。

2. 二维码扫码登录：通过xhs login --qrcode命令，工具会在终端显示一个二维码，用户只需使用小红书APP扫码即可完成登录。这种方式既安全又方便，尤其适合在服务器等无GUI环境下使用。

3. 手动Cookie导入：高级用户可以将已有的Cookie保存为JSON文件，存放在~/.xiaohongshu-cli/cookies.json路径下。工具会自动读取并使用这些Cookie进行认证。

认证状态管理方面，工具会定期检查Cookie的有效性（默认7天有效期），并在检测到失效时自动尝试刷新。这种机制大大减少了因登录状态问题导致的操作中断。

2.2 内容浏览与搜索功能

内容浏览是xiaohongshu-cli最基础也是最重要的功能之一。它实现了多种内容获取方式：

• 关键词搜索：通过xhs search "关键词"命令，可以搜索小红书上的相关内容。支持按热度(--sort popular)或时间(--sort latest)排序，还能过滤内容类型(--type video或--type image)。

• 用户搜索：xhs search-user "用户名"命令专门用于查找特定用户，这对于社交媒体监控或竞品分析非常有用。

• 话题搜索：xhs topics "话题名"可以查找特定话题下的内容，帮助用户发现热点讨论。

• 推荐流：xhs feed命令获取个性化推荐内容，xhs hot -c category则按分类（如美食、旅行等）获取热门内容。

特别设计的"短索引"功能让连续操作变得极其便利。例如，先执行搜索xhs search "黑丝"，然后可以用xhs read 1直接查看搜索结果中的第一条内容，再用xhs comments 1查看其评论，这种流畅的操作体验大大提升了工具的使用效率。

2.3 社交互动功能

作为一个完整的社交媒体工具，xiaohongshu-cli实现了丰富的互动功能：

• 点赞系统：xhs like <note_id>和xhs like <note_id> --undo分别实现点赞和取消点赞操作。

• 收藏功能：通过xhs favorite和xhs unfavorite命令管理收藏内容。

• 评论互动：xhs comment添加评论，xhs reply回复特定评论，xhs delete-comment删除自己的评论。

• 关注管理：xhs follow和xhs unfollow命令管理关注列表。

这些功能不仅完整覆盖了普通用户的互动需求，更为开发者提供了自动化社交互动的可能。例如，可以编写脚本自动给特定话题的内容点赞评论，实现智能化的社交媒体运营。

2.4 内容创作与管理

对于内容创作者，xiaohongshu-cli提供了完整的创作工具链：

• 内容发布：xhs post --title "标题" --body "正文" --images img.jpg命令支持发布图文笔记，满足基本的内容创作需求。

• 内容管理：xhs my-notes查看已发布内容列表，xhs delete <note_id>删除特定内容。

• 数据统计：通过xhs whoami获取账号的基本数据，包括粉丝数、获赞数等。

虽然目前还不支持视频发布和更复杂的内容编辑功能，但对于技术型创作者或需要批量发布简单内容的运营人员来说，这些功能已经能够满足基本需求。

3. 技术实现深度解析

3.1 逆向工程与API签名

xiaohongshu-cli最核心的技术挑战在于逆向工程小红书的API接口。小红书作为一款流行的社交电商平台，其API有着严格的安全防护措施。开发者通过分析网页端和移动端的网络请求，成功破解了以下关键机制：

1. 请求签名：小红书使用x-s、x-s-common和x-t等多层签名验证请求合法性。工具中的signing.py模块实现了完整的签名生成算法，包括：

   • 时间戳处理
   • 设备指纹生成
   • 参数排序和哈希计算
   • 最终签名拼接

2. 设备指纹：constants.py中定义了完整的设备信息，包括：

   USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" DEVICE_FP = "device_web_1234567890abcdef"

   这些信息保持一致性对于避免被风控至关重要。

3. Token管理：小红书API使用xsec_token作为会话令牌，工具会自动从URL提取或通过API获取，并缓存在~/.xiaohongshu-cli/token_cache.json中供后续使用。

3.2 反检测机制实现

为了避免被小红书的风控系统识别和封禁，xiaohongshu-cli实现了一系列精妙的防检测措施：

1. 请求节奏控制：

   • 高斯分布随机延迟：请求间隔不是固定的，而是遵循μ=1s, σ=0.3s的正态分布
   • 随机长暂停：5%的请求会额外延迟2-5秒，模拟人类阅读时间
   • 指数退避重试：遇到错误时等待时间按1s, 2s, 4s递增

2. 浏览器指纹一致性：

   • 所有请求保持相同的User-Agent、屏幕分辨率、GPU信息等设备指纹
   • 使用macOS Chrome的典型配置，包括Retina显示屏和Apple芯片信息
   • Session内保持指纹稳定，模拟真实浏览器行为

3. 验证码处理：

   • 遇到验证码时自动进入冷却期（5→10→20→30秒递增）
   • 冷却后自动降低请求频率
   • 记录验证码触发模式以避免重复触发

这些措施的综合运用，使得工具发出的请求与真实用户行为几乎无法区分，大大降低了被封禁的风险。

3.3 结构化数据输出

xiaohongshu-cli设计了统一的数据输出格式，便于其他程序处理：

1. 输出格式选择：

   • 默认情况下，在终端中显示富文本格式(--rich)
   • 支持通过--json或--yaml参数指定输出格式
   • 当输出被重定向到文件或管道时，自动使用YAML格式

2. 数据封装结构： 所有输出都遵循标准信封格式：

   ok: true schema_version: "1" data: # 实际数据内容 error: null

   这种结构使得错误处理和版本兼容更加容易。

3. 短索引缓存： 每次列表操作（如搜索）的结果会被缓存到~/.xiaohongshu-cli/index_cache.json中，后续可以通过数字索引快速访问特定项，极大简化了脚本编写。

4. 安装与使用指南

4.1 环境准备与安装

xiaohongshu-cli需要Python 3.8+环境，推荐使用较新的Python版本以获得最佳性能。以下是详细的安装步骤：

1. 基础环境准备：

   # 检查Python版本 python3 --version # 安装pipx（推荐用于隔离环境） python3 -m pip install --user pipx python3 -m pipx ensurepath

2. 工具安装：

   # 使用pipx安装（推荐） pipx install xiaohongshu-cli # 或者使用uv工具安装 uv pip install xiaohongshu-cli

3. 从源码安装（开发模式）：

   git clone https://github.com/jackwener/xiaohongshu-cli.git cd xiaohongshu-cli uv pip install -e .

4. 定期升级：

   pipx upgrade xiaohongshu-cli # 或 uv pip install --upgrade xiaohongshu-cli

4.2 基础使用示例

让我们通过几个典型场景来演示工具的基本用法：

1. 登录与认证检查：

   # 通过浏览器Cookie登录 xhs login # 通过二维码登录（适用于无GUI环境） xhs login --qrcode # 检查登录状态 xhs status # 查看当前用户信息 xhs whoami --json

2. 内容搜索与浏览：

   # 搜索"美食"相关内容，按热度排序 xhs search "美食" --sort popular # 查看搜索结果的第3条 xhs read 3 # 查看该条目的所有评论 xhs comments 3 --all # 搜索特定用户 xhs search-user "美食博主"

3. 社交互动：

   # 给当前查看的内容点赞 xhs like 1 # 添加评论 xhs comment 1 -c "这篇文章很有帮助！" # 关注用户 xhs follow user_id_123

4. 内容创作：

   # 发布新笔记 xhs post --title "我的美食日记" --body "今天发现了这家不错的餐厅..." --images food.jpg # 查看已发布内容 xhs my-notes # 删除笔记 xhs delete note_id_456

4.3 进阶使用技巧

1. 批量处理内容：

   # 搜索并自动点赞最近10条关于"Python编程"的内容 xhs search "Python编程" --sort latest | grep -Eo 'note_id":"([^"]+)"' | cut -d'"' -f4 | head -10 | xargs -I{} xhs like {}

2. 数据导出与分析：

   # 将搜索结果导出为JSON文件 xhs search "旅行攻略" --json > travel_notes.json # 提取关键字段进行分析 cat travel_notes.json | jq '.data.items[] | {title: .title, likes: .likes_count}'

3. 结合AI工具使用： 由于工具支持结构化输出，可以轻松与其他AI工具集成：

   # 获取内容并用AI生成摘要 xhs read note_id_789 --json | your_ai_tool --prompt "请用中文总结这篇文章的主要内容"

4. 定时任务设置： 使用cron设置定时任务，例如每天早上8点获取热门内容：

   0 8 * * * /usr/local/bin/xhs hot -c food --json > ~/daily_hot_food_$(date +\%Y\%m\%d).json

5. 常见问题与解决方案

5.1 认证相关问题

1. NoCookieError: No 'a1' cookie found

   • 原因：浏览器中没有找到有效的登录状态
   • 解决方案：
     1. 在任何浏览器中打开小红书网站(https://www.xiaohongshu.com/)并登录
     2. 确保登录状态保持（不要立即关闭浏览器）
     3. 再次运行xhs login

2. SessionExpiredError: Session expired

   • 原因：保存的Cookie已过期（默认7天有效期）
   • 解决方案：
     • 运行xhs login刷新Cookie
     • 或者使用xhs login --qrcode重新登录

3. NeedVerifyError: Captcha required

   • 原因：操作触发了小红书的风控验证
   • 解决方案：
     1. 在浏览器中访问小红书并完成验证码
     2. 等待5-10分钟再重试操作
     3. 考虑降低操作频率

5.2 请求限制问题

1. IpBlockedError: IP blocked by XHS

   • 原因：当前IP地址被小红书暂时封禁
   • 解决方案：
     • 更换网络环境（如切换WiFi或使用手机热点）
     • 等待几小时后再尝试
     • 避免在短时间内发送大量请求

2. 请求响应缓慢

   • 原因：工具内置的防检测延迟机制
   • 优化建议：
     • 这是正常现象，不建议修改延迟参数
     • 对于批量操作，可以考虑并行运行多个实例（但要注意风险）

3. OperationNotAllowedError

   • 原因：尝试执行当前账号权限不允许的操作
   • 解决方案：
     • 检查账号状态是否正常
     • 确认是否有发布敏感内容的历史
     • 换用其他账号尝试

5.3 功能使用问题

1. 短索引不工作

   • 原因：可能没有先执行列表命令，或缓存被清除
   • 解决方案：
     • 确保在执行xhs read N前先执行了搜索或列表命令
     • 检查~/.xiaohongshu-cli/index_cache.json是否存在且有效

2. 图片上传失败

   • 原因：图片格式或大小不符合要求
   • 解决方案：
     • 确保图片是JPEG或PNG格式
     • 将图片大小压缩到5MB以下
     • 尝试更换图片再试

3. 内容搜索不准确

   • 原因：小红书搜索算法调整或API限制
   • 解决方案：
     • 尝试使用更具体的关键词
     • 添加--sort popular参数获取更相关结果
     • 结合多个关键词缩小搜索范围

6. 开发与贡献指南

6.1 项目结构与代码组织

xiaohongshu-cli的代码结构清晰，便于理解和扩展：

xhs_cli/ ├── __init__.py ├── cli.py # 命令行接口主入口 ├── client.py # API客户端核心实现 ├── cookies.py # Cookie管理 ├── signing.py # 请求签名生成 ├── constants.py # 常量定义 ├── exceptions.py # 自定义异常 ├── qr_login.py # 二维码登录实现 ├── formatter.py # 输出格式化 └── commands/ # 具体命令实现 ├── auth.py # 认证相关命令 ├── reading.py # 内容阅读命令 ├── interactions.py # 互动命令 ├── social.py # 社交命令 ├── creator.py # 创作命令 └── notifications.py # 通知命令

这种模块化设计使得添加新功能或修改现有功能都非常方便。例如，要添加一个新命令，只需要在commands目录下创建新的模块，并在cli.py中注册即可。

6.2 开发环境搭建

1. 克隆仓库：

   git clone https://github.com/jackwener/xiaohongshu-cli.git cd xiaohongshu-cli

2. 安装开发依赖：

   uv pip install -e ".[dev]"

3. 运行测试：

   # 单元测试 pytest tests/ -v --ignore=tests/test_integration.py -m "not smoke" # 集成测试（需要有效Cookie） pytest tests/test_integration.py -v

4. 代码风格检查：

   ruff check .

6.3 贡献流程

1. 发现问题或新需求：

   • 在GitHub Issues中查看是否已有相关讨论
   • 如果没有，创建一个新issue描述问题或建议

2. 开发新功能：

   • 从main分支创建新分支
   • 实现新功能或修复bug
   • 添加相应的测试用例
   • 更新文档（README和SKILL.md）

3. 提交Pull Request：

   • 确保所有测试通过
   • 描述变更内容和相关考虑
   • 等待维护者审查

4. 代码审查与合并：

   • 根据反馈进行必要的修改
   • 维护者合并PR后，变更将包含在下一版本中

6.4 扩展开发建议

对于希望扩展功能的开发者，以下是一些有价值的方向：

1. 视频内容支持：

   • 添加视频上传和下载功能
   • 实现视频元数据提取

2. 电商功能集成：

   • 获取商品信息和评价
   • 跟踪商品价格变化

3. 数据分析增强：

   • 添加内容情感分析
   • 实现关键词趋势统计

4. 通知推送：

   • 集成邮件或IM通知
   • 实现关键词监控提醒

5. 用户行为模拟：

   • 更精细的浏览行为模拟
   • 个性化推荐流优化

7. 安全与合规考量

7.1 使用限制与风险提示

虽然xiaohongshu-cli提供了强大的功能，但使用时需要注意以下限制和风险：

1. API变更风险：

   • 小红书可能随时更改其API接口
   • 重大变更可能导致工具部分或全部功能失效
   • 建议关注项目更新并及时升级

2. 账号安全风险：

   • 异常使用模式可能导致账号暂时或永久限制
   • 避免使用主账号进行自动化操作
   • 考虑创建专用账号用于开发和测试

3. 法律合规风险：

   • 大规模数据抓取可能违反小红书的使用条款
   • 商业用途可能需要额外授权
   • 建议咨询法律顾问以确保合规

7.2 最佳实践建议

为了安全有效地使用xiaohongshu-cli，建议遵循以下最佳实践：

1. 请求频率控制：

   • 即使工具内置了防检测机制，仍建议控制总体请求量
   • 大规模操作前先进行小规模测试
   • 避免在短时间内发送大量相似请求

2. 账号管理：

   • 为不同用途创建独立账号
   • 定期检查账号状态
   • 发现异常立即停止相关操作

3. 数据使用：

   • 仅收集必要的数据
   • 妥善存储和处理用户数据
   • 公开数据时进行适当的匿名化处理

4. 监控与日志：

   • 记录重要操作的日志
   • 监控错误率和异常响应
   • 设置操作频率警报

7.3 替代方案比较

当xiaohongshu-cli不能满足需求时，可以考虑以下替代方案：

1. 官方API：

   • 小红书为商家和合作伙伴提供官方API
   • 需要申请和审核
   • 功能更稳定但可能有限制

2. 浏览器自动化：

   • 使用Selenium或Playwright模拟浏览器操作
   • 更接近真实用户行为
   • 但资源消耗更大，速度更慢

3. 移动端自动化：

   • 通过Appium等工具自动化手机APP
   • 可以访问APP专属功能
   • 但实现复杂度更高

4. 第三方服务：

   • 一些公司提供小红书数据API服务
   • 通常收费但更稳定
   • 需要注意数据安全和合规性

8. 实际应用案例

8.1 社交媒体监控

xiaohongshu-cli非常适合用于品牌和产品的社交媒体监控：

1. 竞品分析：

   # 跟踪竞品相关讨论 xhs search "竞品名称" --sort popular --json > competitor_$(date +\%Y\%m\%d).json

2. 用户反馈收集：

   # 获取产品相关讨论并提取关键信息 xhs search "我的产品名称" --all | jq '.data.items[] | select(.comments_count > 5)'

3. 趋势分析：

   # 定期记录关键词热度 echo "$(date),$(xhs search "关键词" | jq '.data.items | length')" >> trend.csv

8.2 内容运营自动化

对于运营团队，可以构建自动化工作流：

1. 定时发布：

   # 示例Python脚本实现定时发布 import subprocess from datetime import datetime def schedule_post(time, title, content, image): while datetime.now() < time: pass subprocess.run(["xhs", "post", "--title", title, "--body", content, "--images", image])

2. 互动增强：

   # 自动回复热门内容下的评论 xhs comments 热门内容ID --all | grep -E '有趣|有帮助' | while read comment; do xhs reply 热门内容ID --comment-id ${comment.id} -c "感谢您的认可！" done

3. 数据报表生成：

   # 生成每周运营报告 xhs whoami --json > stats.json xhs my-notes --json | jq '.data.items | length' >> stats.json # 进一步处理生成可视化报表

8.3 数据分析与研究

学术研究人员可以使用工具进行社交媒体研究：

1. 内容分析：

   # 收集特定话题的内容进行语言学分析 xhs search "心理健康" --all --json | jq '.data.items[].content' > mental_health_content.txt

2. 用户行为研究：

   # 分析热门内容的特征 xhs hot -c travel --json | jq '.data.items[] | {likes: .likes_count, comments: .comments_count, title_length: (.title | length)}'

3. 网络传播研究：

   # 跟踪特定内容的传播路径 xhs read 初始内容ID --json | jq '.data.related_notes' > propagation_nodes.json

8.4 个人知识管理

个人用户也可以利用工具增强小红书使用体验：

1. 内容收藏与归档：

   # 将收藏内容保存为Markdown文件 xhs favorites --json | jq -r '.data.items[] | "## \(.title)\n\n\(.content)\n\n"' > my_favorites.md

2. 个性化推荐优化：

   # 定期点赞感兴趣的内容以训练推荐算法 xhs feed | grep -E "Python|编程" | awk '{print $1}' | xargs -I{} xhs like {}

3. 跨平台分享：

   # 将小红书内容自动分享到其他平台 xhs read 精彩内容ID --json | extract_content.sh | post_to_other_platform.sh

9. 性能优化与高级配置

9.1 请求优化技巧

1. 并发控制： 虽然工具本身是单线程的，但可以通过一些技巧实现并行处理：

   # 使用GNU parallel并行处理 cat note_ids.txt | parallel -j 4 'xhs read {} --json > {}.json'

   注意：并发数(-j)不宜过高，建议不超过5。

2. 缓存利用： 工具会自动缓存部分数据，也可以通过脚本手动缓存：

   # 预加载并缓存热门内容 xhs hot -c food --all > /dev/null

3. 请求字段选择： 某些命令支持--fields参数指定返回字段，减少不必要的数据传输：

   xhs search "关键词" --fields "id,title,likes_count"

9.2 配置文件定制

工具支持通过配置文件~/.xiaohongshu-cli/config.yaml进行个性化设置：

# 默认输出格式 output_format: json # 请求延迟配置 request: base_delay: 0.8 # 基础延迟(秒) jitter: 0.3 # 随机抖动范围 # 缓存设置 cache: ttl: 3600 # 缓存有效期(秒) enabled: true # 是否启用缓存

9.3 代理配置

在某些网络环境下，可能需要配置代理：

# 临时使用代理 https_proxy=http://proxy.example.com:8080 xhs search "关键词" # 或写入配置文件 echo "proxy: http://proxy.example.com:8080" >> ~/.xiaohongshu-cli/config.yaml

9.4 日志与监控

1. 请求日志记录：

   # 启用详细日志 XHS_DEBUG=1 xhs search "关键词" 2> xhs.log

2. 性能监控：

   # 使用time命令测量执行时间 time xhs search "关键词" --all --json > results.json

3. 错误报警：

   # 监控错误率并发送通知 xhs search "关键词" || send_alert "小红书API请求失败"

10. 生态整合与未来展望

10.1 与其他工具的集成

xiaohongshu-cli可以轻松与其他开发工具和数据平台集成：

1. 数据可视化：

   # 将数据导入Pandas进行分析 xhs search "关键词" --json | python -c "import pandas as pd; import sys; df=pd.read_json(sys.stdin); print(df.describe())"

2. 自然语言处理：

   # 使用NLP工具分析内容情感 xhs comments 内容ID --all | jq '.data[].content' | your_nlp_tool --task sentiment

3. 工作流自动化：

   # 与Zapier或Make.com集成实现自动化 xhs search -n 5 "品牌名" --json | curl -X POST -d @- https://hooks.zapier.com/...

10.2 AI Agent集成

项目提供的SKILL.md使得xiaohongshu-cli可以轻松被AI Agent使用：

1. 技能安装：

   npx skills add jackwener/xiaohongshu-cli -g

2. 典型AI指令示例：

   请使用xiaohongshu-cli搜索最近一周关于"可持续时尚"的热门内容， 提取点赞超过1000的笔记，并总结它们的共同特点。

3. 自动化内容创作：

   分析当前热门的美妆趋势， 基于这些趋势创作一篇小红书笔记草稿， 并使用xiaohongshu-cli发布。

10.3 项目发展方向

基于当前代码结构和社区需求，项目未来可能会向以下方向发展：

1. 更丰富的电商功能：

   • 商品搜索与比价
   • 购物车管理
   • 订单跟踪

2. 增强的内容创作：

   • 富文本编辑支持
   • 多图排版优化
   • 定时发布功能

3. 数据分析增强：

   • 内置基础分析功能
   • 可视化图表生成
   • 竞品对比工具

4. 跨平台整合：

   • 与其他社交平台的数据互通
   • 统一的内容管理界面
   • 跨平台数据统计分析

5. 企业级功能：

   • 多账号管理
   • 团队协作支持
   • 权限与审核流程

10.4 社区与支持

项目拥有活跃的开发者社区，用户可以通过以下方式获取支持：

1. GitHub讨论区：

   • 报告问题和提出建议
   • 分享使用经验
   • 参与功能讨论

2. 贡献指南：

   • 清晰的代码规范
   • 详细的开发文档
   • 友好的PR流程

3. 生态系统：

   • 相关工具推荐(bilibili-cli, twitter-cli等)
   • 插件系统规划
   • 第三方集成列表

随着小红书的持续发展和API的演进，xiaohongshu-cli也将不断更新以适应这些变化，为开发者提供更强大、更稳定的工具支持。