如何3分钟上手xhs-cli:uv/pipx一键安装与首次登录配置教程

原创2026-11-03 21:39:292,317 阅读
文章标签:CLI社交AI 技能网页爬虫

如何3分钟上手xhs-cli:uv/pipx一键安装与首次登录配置教程

xhs-cli 是一款小红书命令行工具,让你直接在终端里完成搜索笔记、阅读详情、点赞、收藏、评论等日常操作,无需打开浏览器。本教程带你用 uv 或 pipx 一键安装 xhs-cli,并走完首次登录配置,3 分钟即可在命令行刷小红书。

为什么要在终端里刷小红书?

传统方式需要在浏览器里点来点去,而 xhs-cli 把常用功能都收敛成简短命令:

你能做什么 对应命令 说明
🔍 搜索笔记 xhs search "咖啡" Rich 表格展示结果
📖 阅读笔记 xhs read <note_id> 可加 --comments 看评论
❤️ 点赞 / 收藏 xhs like / xhs favorite 支持 --undo 撤销
💬 发表评论 xhs comment <note_id> "好棒!" 一条命令搞定
📝 查看自己 xhs whoami 查看个人资料

所有数据命令还支持 --json 输出,方便和 jq 等工具组合成自动化流程,详见 README.md 的命令一览表。

快速安装 xhs-cli:uv 与 pipx 两种一键命令

xhs-cli 需要 Python 3.8+,推荐用 uv 或 pipx 隔离安装,不污染系统环境。

方式一:uv 安装(推荐,最快)

uv tool install xhs-cli

uv 会自动创建虚拟环境、拉取依赖并把 xhs 命令放到 PATH 中,通常十几秒就完成。

方式二:pipx 安装

如果你已经熟悉 pipx,同样一条命令:

pipx install xhs-cli

💡 两个安装命令都会自动装好依赖(camoufox、playwright、rich 等),你不需要手动 pip install 任何东西。

验证安装是否成功

xhs --version

能输出版本号(如 0.1.4)就说明安装成功。也可以运行 xhs --help 查看全部可用命令。

首次登录配置:三种方式任选其一

登录是第一次使用最关键的一步。xhs-cli 的认证逻辑在 xhs_cli/auth.py 中实现,按优先级依次尝试:本地已保存 cookie → 自动提取本地 Chrome cookie → 二维码扫码登录。

方式一:自动提取 Chrome cookie(最省事)

如果你平时在 Chrome 里登录过小红书,直接运行:

xhs login

工具会通过 browser-cookie3 从本地 Chrome 中提取 a1、web_session 等关键 cookie 并保存到 ~/.xhs-cli/cookies.json(权限 0600),全程无需手动复制粘贴。

方式二:终端二维码扫码登录

不方便提取 cookie 时,可以用二维码登录(终端直接渲染二维码,用小红书 App 扫码即可):

xhs login --qrcode

方式三:手动提供 cookie 字符串

从浏览器开发者工具复制 cookie 后手动传入(至少包含 a1 和 web_session 两项):

xhs login --cookie "a1=xxx; web_session=yyy"

检查登录状态

登录后建议做两步检查:

xhs status   # 快速检查本地已保存的登录态(不启动浏览器)
xhs whoami   # 查看自己的个人资料,验证会话真实有效

⚠️ 注意:xhs status 只检查本地文件,xhs whoami 才会真正请求服务端验证。若会话仍是 guest 或受限状态,重新执行 xhs login 即可。

登录后必做的 1 件事:下载 camoufox 浏览器

xhs-cli 的底层原理是让 camoufox(反指纹 Firefox)像真实用户一样打开页面,再从 window.__INITIAL_STATE__ 提取结构化数据,互动操作(点赞、评论)也是点击真实 DOM 按钮完成的。因此首次运行前需要下载一次浏览器内核:

python -m camoufox fetch

整个过程使用 headless 模式,不会弹出浏览器窗口,下载完成后即可长期使用。

上手后的下一步:跑一条搜索试试

登录成功后,先来一条搜索感受下效果:

xhs search "咖啡"

搜索结果会以表格呈现。一个贴心的设计是:搜索后每篇笔记的 xsec_token 会自动缓存到 ~/.xhs-cli/token_cache.json,之后执行 xhs read、xhs like 等命令时无需再手动传递 token,直接填笔记 ID 就行。

想继续体验评论、发布等功能,可以查阅 SKILL.md 中的完整命令参考;也可以运行仓库自带的冒烟测试脚本 scripts/smoke_local.sh 做一次本地自检。

常见问题快速排查

问题 解决办法
Not logged in 提示未登录 执行 xhs login 重新登录
登录后显示 guest / 探活失败 重新执行 xhs login 刷新会话
Chrome 提取 cookie 失败 改用 xhs login --qrcode 扫码
想看详细报错日志 命令前加 -v,如 xhs -v search "咖啡"
想彻底退出登录 xhs logout 清除本地 cookie

更多版本变更记录可查看 CHANGELOG.md,核心命令入口位于 xhs_cli/cli.py。

小结

  • 安装:uv tool install xhs-cli 或 pipx install xhs-cli,一条命令搞定
  • 登录:xhs login 自动提取 Chrome cookie,扫码兜底
  • 验证:xhs status + xhs whoami 双重确认
  • 使用:xhs search、xhs read、xhs like 等命令覆盖搜索、阅读、互动全流程

配置完成后,你的终端就变成了一个轻量级小红书客户端。祝使用愉快!🍰

登录后查看全文
xhs-cli