如何3分钟上手xhs-cli:uv/pipx一键安装与首次登录配置教程
如何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等命令覆盖搜索、阅读、互动全流程
配置完成后,你的终端就变成了一个轻量级小红书客户端。祝使用愉快!🍰