[Suggestion] WSL2 下 xhs login --qrcode 因无图形界面崩溃；建议利用 WSLg + Camoufox 做可视化登录备用方案

[heibaiaxx1]

背景

xhs login --qrcode 会启动一个带界面的 Camoufox 浏览器（qr_login.py:359 行硬编码了 headless=False），用来加载小红书登录页并在终端显示二维码。

问题

这个浏览器辅助登录在 WSL2 上直接崩溃，因为 WSL2 没有原生的 X11 显示服务。Playwright 启动 Firefox 时会立刻报错：

复制

Error: Failed to launch the browser process.
Looks like you launched a headed browser without having a XServer running.

就算终端二维码能正常显示，完整的登录流程还可能涉及验证码嵌套：扫码 → 短信验证 → 再次扫码（1 分钟有效期的二维码）。纯终端操作无法完成这套流程。

这意味着 WSL2 用户（Windows 上跑 WSL2 做开发或跑 AI Agent 的常见场景）无法可靠地通过 xhs login --qrcode 完成登录认证。

现有方案及其局限

SKILL.md 的认证指南建议用 browser_cookie3 从已安装的 Windows 浏览器中提取 cookie。但：

• browser_cookie3 在 WSL2 里不一定能识别到所有 Windows 浏览器
• 如果 Windows 浏览器里没有小红书的有效登录态，用户还是得走一遍登录流程
• 对于短信验证码、二次验证码嵌套的场景，没有文档化备用方案

建议方案：利用 WSLg + Camoufox 做可视化登录

Windows 11 自带的 WSLg 能让 WSL2 里的图形程序直接显示在 Windows 桌面上，不需要任何额外软件。

为什么不能直接用 xhs login --qrcode？
xhs login --qrcode 通过 Playwright API 启动 Camoufox，虽然设置了 headless=False，但在 WSL2 中因为没有 X Server 会直接崩溃。即使设了 DISPLAY=:0，Playwright 在无头环境中启动 headed 浏览器的流程也会失败。而直接启动 Camoufox 二进制文件（~/.cache/camoufox/camoufox）则能利用 WSLg 正常显示窗口。

用户只需在 WSL2 里安装 xiaohongshu-cli（它已依赖 Camoufox），然后：

1. export DISPLAY=:0
2. 手动启动 Camoufox：~/.cache/camoufox/camoufox --new-instance --profile ~/.xhs-login-profile "https://www.xiaohongshu.com"
3. 浏览器窗口自动弹出在 Windows 桌面上，用户可视化完成登录（扫码 + 短信验证 + 任何验证码）
4. 登录后从 Camoufox 的 cookies.sqlite 中读取 a1 和 web_session
5. 写入 ~/.xiaohongshu-cli/cookies.json
6. 完成

Camoufox 提供了更好的指纹伪装，在被风控拦截时可以提升成功率。

与现有方案的对比

方案 | 能否处理验证码嵌套 | WSL2 兼容 | 反风控能力 -- | -- | -- | -- --qrcode | ❌ 纯终端搞不定验证码 | ❌ 无 X Server 直接崩溃 | ✅ Camoufox 指纹伪装 browser_cookie3 | ❌ 依赖已有 Windows 浏览器 session | ✅ | ❌ 依赖 Windows 浏览器环境 WSLg + Camoufox（建议） | ✅ 完整可视化验证流程 | ✅ | ✅ Camoufox 指纹伪装

建议的文档位置

在 README.md 或 SKILL.md 的 Authentication 章节新增一小节：

WSL2 / 无头环境备用方案：
如果 xhs login --qrcode 在你的 WSL2 环境中因缺少图形界面而报错，或你需要处理短信验证码等交互式验证，可以利用 WSLg（Windows 11 内置）直接启动 Camoufox 浏览器进行可视化登录：

bash复制

export DISPLAY=:0
~/.cache/camoufox/camoufox --new-instance --profile ~/.xhs-login-profile "https://www.xiaohongshu.com"

登录后从 ~/.camoufox/<profile>/cookies.sqlite 中提取 a1 和 web_session，写入 ~/.xiaohongshu-cli/cookies.json 即可。