小红书无水印下载器使用说明

一个纯浏览器端、不依赖任何本地程序的小红书作品下载脚本。 基于开源项目 XHS-Downloader 的源码与原生 userscript 逆向复刻。

一、它能做什么

• 下载本篇：在作品详情页（URL 形如 …/explore/xxxx）一键下载当前作品的全部图片或视频。
• 下载本页全部：在首页 / 搜索结果 / 用户主页 / 合集页，批量下载当前页面所有可见作品。
• 复制本页链接：把本页所有作品的标准分享链接（…/explore/{noteId}?xsec_token=…）复制到剪贴板。
• 全程在浏览器内完成，无需安装 Python、无需启动本地服务、无需 Cookie 配置。

二、安装步骤

1. 浏览器安装油猴扩展：
   • Chrome / Edge：Tampermonkey（Chrome 应用商店搜索 "Tampermonkey"）
   • Firefox：Greasemonkey / Tampermonkey
2. 打开 Tampermonkey 管理面板 → 「+ 添加新脚本」或「创建脚本」。
3. 把 XHS-Downloader-Userscript.user.js 的全部内容粘贴进去，保存（Ctrl+S）。
4. 也可以直接把 .user.js 文件拖入 Tampermonkey 窗口完成安装。
5. 打开任意小红书页面（需登录态，否则部分作品数据拿不全），右上角出现红色「XHS 独立下载器」面板即表示生效。

支持的站点：www.xiaohongshu.com 与 www.rednote.com（红笔记国际版）。

三、使用指南

面板各控件说明：

• 面板可拖动（按住标题栏「XHS 独立下载器」拖动）。
• 所有设置（图片格式、视频偏好、滚动配置）会自动保存，下次打开沿用。
• 下载过程中面板顶部状态栏会实时显示进度，例如「下载图片 3/5」「下载中 12/40」。

四、工作原理（详细）

1. 数据从哪来 —— 读取页面全局状态

小红书把所有作品数据都挂在页面的全局变量 window.__INITIAL_STATE__ 上。脚本直接读取它，而不是去爬 DOM 或请求接口，因此不需要 Cookie、不需要额外请求。

不同页面的数据路径：

每个笔记对象自带 noteId、type（normal / video）、imageList、video、title、user 等字段。

关键设计：取「当前作品」时，脚本先用 URL 里的 noteId 去 note.noteDetailMap[id].note 精确匹配（见下方「已修复问题」），避免误取信息流卡片。

2. 图片直链怎么生成

从 note.imageList[*] 里取每张图的地址（优先 urlDefault，其次 url，再其次 urlPre），抠出其中的资源 token，拼成可直连下载的地址。

为最大化成功率，每张图会生成三个候选地址，按顺序尝试：

1. https://ci.xiaohongshu.com/{token}?imageView2/format/{fmt} —— 格式可控的原图（与官方 XHS-Downloader 的 image.py 逻辑一致）。
2. https://sns-img-bd.xhscdn.com/{token} —— 原项目 image.py 中的 "auto" 直链。
3. 原始 CDN 直链：把 urlDefault 去掉 ! 变换后缀得到的未处理原图（同域，最稳，作为兜底）。

3. 视频直链怎么生成

• 优先用 note.video.consumer.originVideoKey → https://sns-video-bd.xhscdn.com/{key}。
• 否则从 note.video.media.stream 各清晰度档位中，按你选择的偏好（分辨率 / 码率 / 体积）取最优档的 backupUrls[0] 或 masterUrl。

4. 文件怎么存到本地

小红书的 CDN（xhscdn、ci.xiaohongshu.com）允许跨域 fetch，所以脚本：

fetch(直链) → 读取为 Blob → URL.createObjectURL → 生成 <a download> 触发浏览器保存

全程在浏览器内闭环，文件直接落盘到浏览器默认下载目录。

5. 文件命名规则

{标题}_{作者}_{作品ID}_{图片序号}.{格式}     # 图文，如 春日穿搭_小红薯abc_65a1b2_1.jpeg
{标题}_{作者}_{作品ID}.mp4                   # 视频

标题 / 作者会做安全化处理（去掉 \ / : * ? " < > | 等非法字符，并截断到 60 字以内）。

五、已修复：多图只下一张

早期版本存在「明明好几张图却只下到一张」的问题，根因与修复如下：

根因 1 —— 取错了笔记对象 旧逻辑直接取页面全部笔记的「最后一个」，在详情页数据尚未加载完（__INITIAL_STATE__ 水合未完成）时，容易拿到信息流卡片，而卡片的 imageList 往往只有 1 张封面图。

修复：currentNote() 改为

• 先按 URL 的 noteId 精确匹配 note.noteDetailMap[id].note；
• 抓不到就轮询最多 15 次（每次 300ms）等待页面数据就绪；
• 再退而求其次用 noteData.data.noteData 或 noteDetailMap 里的笔记。

根因 2 —— 直链只有单一来源 旧版图片直链只靠 ci.xiaohongshu.com 一条路，某张图 token 解析异常就整张失败。

修复：imageCandidates() 为每张图生成 3 个候选地址依次尝试；downloadFile() 支持候选数组、加了图片 accept 请求头、并校验空文件；downloadNote() 逐张显示进度与成功数（如「图片下载完成：5/5 张」）。

六、配置项（自动保存）

设置通过油猴的 GM_setValue / GM_getValue 持久化，键名与默认值：

七、代码结构（模块速览）

脚本为单一 IIFE，无外部依赖，主要分区：

• 工具函数：$ / $$（选择器）、sleep、getState（读 __INITIAL_STATE__）、safeGet / safeArr（安全取值，避免路径中间为 null 报错）。
• 笔记收集：collectNotes()（本页全部笔记，用于「下载本页全部 / 复制链接」）、extractCurrentNoteId() + getDetailNote() + currentNote()（精确且带重试地取当前详情页作品）。
• 直链生成：imageCandidates()（图片多候选）、videoUrl()（视频最优档）。
• 下载核心：downloadFile()（fetch + Blob + 候选兜底 + 重试）、triggerDownload()（<a download> 落盘）、downloadNote()（按类型分发、逐张进度）。
• 自动滚动：autoScroll()（触发懒加载）。
• UI：buildUI()（面板与控件）、toast()（提示）、makeDraggable()（拖拽）。
• 启动：init() 在 document-idle 后注入面板。

八、已知限制与注意事项

1. 需登录态：未登录或登录过期时，部分作品的 imageList / video 字段可能缺失，导致下载不全。
2. 浏览器多文件下载：一次性触发大量下载时，Chrome / Edge 可能弹出「是否允许本站点多次下载」的确认框，请点击「允许」；否则后续文件会被拦截。
3. 懒加载内容：在很长的列表页，未滚动到的作品尚未进入 __INITIAL_STATE__，需勾选「自动滚动加载」先把内容滚出来。
4. 清晰度选择：图片格式选择 HEIC / AVIF 时，部分操作系统自带的图片查看器可能不识别，属正常现象。
5. 合规使用：本脚本为「可见即可得」的采集方式，请仅用于下载自己发布或已授权的内容，遵守平台条款与版权法规。

九、故障排查

文档对应脚本版本：v2.0.0