带内置浏览器的小红书媒体下载与个人备份工具
一个下载核心，两种自包含入口：图形界面与命令行
挖红薯用于保存你在小红书页面中能够正常访问的图片、Live Photo 和视频。 它会尽量选择页面公开提供的最高质量媒体，并按照笔记标题整理文件。除了单篇 笔记，也能按顺序批量处理博主主页和“我的收藏”。
Important
挖红薯不是小红书官方产品，也不会绕过账号权限或访问控制。请只保存自己 拥有、已获授权或法律允许使用的内容，并阅读 使用说明与免责声明。
| 能力 | 说明 |
|---|---|
| 单篇笔记 | 下载当前笔记中的图片、Live Photo 或视频 |
| 博主主页 | 输入准确数量，按页面从前到后的顺序批量下载 |
| 我的收藏 | 使用内置浏览器中已经登录的账号读取并批量下载 |
| 高质量媒体 | 图片优先选择无网页转换参数的公开主资源；视频优先选择最高质量的兼容 H.264 流 |
| Live Photo | 同时保存静态图片和对应的动态视频部分 |
| 清晰的文件名 | 使用“笔记标题 + 编号”命名，单篇内容保存到“标题 + 笔记 ID”文件夹 |
| 批次目录 | 博主主页按“博主名 + 主页 ID”建立汇总文件夹，照片和视频直接平铺其中；文件名含笔记 ID，避免重名 |
| 图形界面与 CLI | GUI 适合点选操作；CLI 提供实时结构化进度、退出码和断点续传，适合脚本与 AI |
这里所说的“最高质量”是页面当时公开提供的最佳媒体，不保证与发布者上传 前的本地原文件逐字节一致。格式、元数据和画质仍可能受到平台处理影响。
图形界面适合日常使用，不需要准备 Python、Node.js 或额外的主程序目录。
- 从 GitHub Releases
下载
WaHongShu-<版本>.exe，双击运行。 - 第一次使用时，在内置浏览器中登录小红书。登录状态会保存在本机，之后无需 每次重新登录。
- 在内置浏览器中打开单篇笔记、博主主页或“我的收藏”。也可以把从其他地方 复制的小红书链接直接粘贴到顶部地址栏。
- 右侧面板识别页面后，单篇笔记可以直接下载；主页和收藏页可以准确填写需要 下载的前多少篇。任务卡片会持续显示当前标题、进度和结果。
界面还提供：
- 自定义下载目录，默认位置是 Windows“下载”文件夹中的
挖红薯。 - 50%–200% 的内置网页缩放，以及
Ctrl＋、Ctrl−、Ctrl＋0快捷键。 - 一键打开下载目录。
- 停止正在扫描或下载的任务。
- 任务卡片实时显示页面识别、当前笔记、进度和错误；GUI 启动时不会附带命令行黑框。
Release 同时提供 WaHongShu-<版本>.exe（GUI）和
WaHongShu-CLI-<版本>.exe（CLI）。二者都是可单独复制运行的自包含 EXE，
不需要旁挂程序目录；CLI 内部复用同一套浏览器会话和下载核心，适合自动化
脚本、批处理和 AI Agent。第一次使用仍应先打开 GUI 完成登录。
下面以 PowerShell 为例：
# 查看帮助和版本
& ".\WaHongShu-CLI-1.2.0.exe" --help
& ".\WaHongShu-CLI-1.2.0.exe" --version
# 下载单篇笔记
& ".\WaHongShu-CLI-1.2.0.exe" download "<小红书笔记链接>"
# 下载博主主页前 5 篇
& ".\WaHongShu-CLI-1.2.0.exe" profile "<博主主页链接>" --limit 5
# 断点续传：只处理没有成功 manifest 的笔记
& ".\WaHongShu-CLI-1.2.0.exe" profile --all --resume "<博主主页链接>"
# 扫描到主页末尾，并输出适合 AI 实时读取的 JSONL 进度
& ".\WaHongShu-CLI-1.2.0.exe" profile --all --resume --jsonl "<博主主页链接>"
# 只预演断点续传数量，不下载任何文件
& ".\WaHongShu-CLI-1.2.0.exe" profile --all --resume --dry-run --json "<博主主页链接>"
# 下载“我的收藏”前 3 篇
& ".\WaHongShu-CLI-1.2.0.exe" favorites "<收藏页链接>" --limit 3
# 本次任务临时指定保存位置，不修改图形界面中的偏好设置
& ".\WaHongShu-CLI-1.2.0.exe" download "<小红书笔记链接>" `
"--output-dir=D:\Media\挖红薯"
# 输出单行 JSON，方便脚本或 AI 读取
& ".\WaHongShu-CLI-1.2.0.exe" profile "<博主主页链接>" `
--limit 5 --json成功时进程退出码为 0，参数错误或下载失败时为非 0。小红书链接通常包含
&，在 PowerShell 中应始终放在引号内。--limit 接受 1–1000 的整数；
--output-dir=目录 必须作为一个完整参数传入。
--resume 是显式的批量断点续传开关，只适用于博主主页和收藏页。它以成功写入
的 manifest.json 为准跳过已经完成的笔记；不写这个开关时仍会照常重新下载，
不会自动去重。--dry-run 只返回扫描、跳过和待下载数量，不会写入媒体文件。
--all 会持续滚动到页面末尾；--jsonl 在标准输出中逐行输出结构化进度事件，
并在结束时输出最终 JSON。遇到登录或安全验证时，批量任务会立即暂停并返回
AUTH_REQUIRED 或 LOGIN_REQUIRED。只有显式添加 --list 时，预演结果才会
附带完整笔记 ID 清单，避免普通 AI 调用收到过大的 JSON。
CLI 不带参数时显示帮助；需要图形界面时运行不带 -CLI 的 EXE。
单篇笔记使用独立文件夹。博主主页批量任务则把所有照片和视频直接平铺到一个 “博主名 + 主页 ID”目录中，媒体顺序仍保留在文件名里：
下载目录/
└─ 博主名_[主页ID]/
├─ 笔记标题_[笔记ID]_01.jpg
├─ 笔记标题_[笔记ID]_01_Live.mp4
├─ batch_manifest.json
└─ _manifests/
└─ 笔记ID.json
单篇任务中的普通视频会保存为 笔记标题_01.mp4 等实际媒体格式。批量任务的
每篇元数据保存在 _manifests/笔记ID.json，batch_manifest.json 则汇总整批
笔记和媒体数量；其中会记录媒体尺寸、格式和所选公开资源等信息，访问 Token
会被遮盖。默认每次执行都会重新下载；只有明确传入 --resume 才跳过已完成项。
- 偏好设置保存在
%APPDATA%\挖红薯\settings.json。 - 小红书浏览器会话保存在同一应用数据目录，并额外写入使用 Windows 系统加密
的
xhs-session.bin备份。 - 登录信息不会写入 EXE、媒体下载目录或运行日志。
- 程序不会上传下载历史、Cookie 或媒体文件。
- 内置地址栏只允许打开小红书及其分享短链域名。
如果希望完全退出账号，可以在应用设置中打开数据目录并清理对应会话数据。
当前便携版没有商业代码签名，因此 Windows SmartScreen 可能显示“未知发布者”。
请只从本仓库的 Releases 页面下载。每个 Release 都同时提供 .exe.sha256
校验文件，可在 PowerShell 中核对：
Get-FileHash -Algorithm SHA256 ".\WaHongShu-1.2.0.exe"
Get-FileHash -Algorithm SHA256 ".\WaHongShu-CLI-1.2.0.exe"输出应与同一 Release 中 .exe.sha256 文件记录的值一致。
开发环境需要 Windows、Node.js、npm，以及 Python 3.11 或更高版本。
git clone https://github.com/xuziqiu/wahongshu.git
cd wahongshu
npm ci
npm start运行全部测试：
npm test构建自包含 Windows 便携版：
python -m pip install pillow pyinstaller
npm run dist:local本地构建脚本会在纯英文的 Windows 临时目录中完成封装，以避开部分打包工具对
中文路径的兼容问题。最终会在 release/ 生成 GUI、CLI 两个自包含 EXE 及各自
的 SHA-256 文件。它们共享同一应用数据目录、登录会话、设置和下载核心。
app/ Electron 桌面程序、内置浏览器、任务编排与界面
cli/ 独立 CLI EXE 启动器与实时输出桥接
core/downloader.py 单篇笔记媒体下载核心
tests/ Python 下载核心测试
app/tests/ 桌面端、发布脚本与会话保存测试
design/branding/ 生图源稿；由脚本裁切为最终应用图标
scripts/ Windows 本地构建与发布收尾脚本
.github/workflows/ 源码测试持续集成；Release 使用本地验证成品直接上传
release/ 本地构建成品；二进制不提交到 Git
源码采用 MIT License。使用本项目时仍需遵守适用法律、平台规则、 著作权和个人信息保护要求。