XHS-Downloader 完整教程：快速上手小红书无水印作品下载

【免费下载链接】XHS-Downloader小红书（XiaoHongShu、RedNote）链接提取/作品采集工具项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader

你一定遇到过这个卡点：想保存小红书上的作品，存下来的图片带着一层水印，视频只能拿到低清版，作品一多更得手动一个个复制链接。XHS-Downloader 就是为了解决这个问题而生的——它是一个小红书作品采集工具，粘贴作品链接后，直接下载无水印的图片和视频原文件，已下载过的作品还会自动跳过。

它到底能帮你做什么

一句话定位：把"小红书作品链接"变成"落在你硬盘上的无水印文件"，顺带把作品数据也存下来。

• 如果你是做内容的创作者，它会帮你把作品链接变成无水印高清图/视频，图文作品还能按图片序号挑着下载；
• 如果你是素材库管理者，它会把每个作品存进单独文件夹、按作者归类、文件名按模板生成，找素材不靠翻；
• 如果你在做数据采集，它能把点赞、收藏、评论、作品标签这些信息存进本地 SQLite 或文本文件；
• 如果你在搭自己的工作流，它提供 API 和 MCP 两种服务接口，浏览器端还有配套用户脚本可以直接推送下载任务。

看完定位，下一步去"三条路径"里选一条，先把程序跑起来。

三条路径，选一条进门

路径一 · 读得懂：直接运行可执行程序适合：只想下载作品、不想碰代码的用户。 从 Releases 下载对应系统（macOS、Windows 10 及以上）的压缩包，解压后双击运行main即可。文件默认保存在Volume\Download，配置文件是Volume\settings.json。 macOS 首次运行被系统拦截时，在终端执行一次：

xattr -cr 项目文件夹路径

路径二 · 改得动：源码运行适合：要自定义参数、做二次开发或参与开发的开发者。需要先装 Python 3.12 及以上版本：

git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader cd XHS-Downloader uv sync --no-dev uv run main.py

不带参数启动的是图形界面；带参数（如-u）进入命令行模式。

路径三 · 跑得起：Docker 容器适合：服务器环境，或要常驻 API / MCP 服务的人。

docker pull joeanamier/xhs-downloader docker run --name xhs -p 5556:5556 -v xhs_downloader_volume:/app/Volume -it joeanamier/xhs-downloader

在命令末尾追加python main.py api或python main.py mcp可以分别以 API、MCP 模式启动。注意：Docker 下不支持命令行参数模式和剪贴板功能，只能直接粘贴内容。

三条路径里，Cookie 都不是必填项，但下载异常时它往往是第一嫌疑，后面排查一节会讲怎么拿到。跑起来之后，按需取用下面的能力。

核心能力，按需取用

无水印下载：一条命令拿到原文件

• 解决什么：水印和低清视频。它拿的是平台原始文件，视频还能在分辨率、码率、文件大小三种偏好里选优先级（--video_preference，默认resolution）。

• 最直接的一招：

  uv run main.py --url "https://www.xiaohongshu.com/explore/作品ID?xsec_token=XXX"

  图文作品想换格式就加--image_format WEBP（支持 PNG、WEBP、JPEG、HEIC、AUTO）。

• 适合谁：所有人，这是使用频率最高的功能。

批量链接：一串链接粘进去，按顺序处理

• 解决什么：作品多时一个个复制链接的麻烦。支持一次输入多个作品链接，用空格分隔；xhslink.com短链接也认，程序会自动从中提取有效作品链接，无需预处理。

• 最直接的一招：

  uv run main.py --url "链接1 链接2 链接3"

• 适合谁：一次要处理一批作品的人。

整理下载：文件夹、文件名、去重一次配齐

• 解决什么：文件散乱、命名混乱、重复下载三件事。

• 最直接的一招：

  uv run main.py --url "链接1 链接2" --folder_mode true --author_archive true

  --folder_mode true让每个作品独占一个文件夹；--author_archive true按作者ID_作者昵称归组；--name_format控制文件名，字段用空格分隔（如"发布时间 作者昵称 作品标题"）。另外download_record默认开启，已下载过的作品会自动跳过，重复跑命令不会产生重复文件。

• 适合谁：准备长期沉淀素材库的人。

留存数据：只采集信息，不下载文件

• 解决什么：你想要的是点赞、收藏、评论数、作品标签这些数据，而不是文件本身。
• 最直接的一招：加--record_data true，作品数据会写入本地 SQLite（默认Volume/Download/ExploreData.db）；再加--note_format md，每个作品的信息额外存一份 Markdown。
• 适合谁：做竞品分析、内容研究的人。

浏览器用户脚本：页面上直接提取链接

• 解决什么：在小红书网页上刷到一批好内容时，手动复制链接太慢。
• 最直接的一招：安装 Tampermonkey 扩展，导入仓库里的 static/XHS-Downloader.js 脚本，之后在页面脚本菜单里就能提取推荐流、发布、收藏、点赞、搜索结果的作品链接；把配置文件里script_server设为true并保持程序在后台运行，还能把"推送下载任务"直接发给本地程序。
• 适合谁：大量时间泡在小红书网页版的人。

提醒一句：脚本的"自动滚动页面"功能默认关闭，开启后可能被平台判定为自动化操作，有账号风控风险，别轻易开。

API / MCP：把它变成能被调用的服务

• 解决什么：你写的程序或 AI 助手想直接触发下载、获取作品数据。

• 最直接的一招：

  uv run main.py api # 启动 API 服务，默认端口 5556 uv run main.py mcp # 启动 MCP 服务（需先安装 fastmcp>=4.1.0）

  API 文档自动生成在http://127.0.0.1:5556/docs；接口调用要在请求头带Authorization: Bearer <令牌>，令牌用uv run main.py token生成，与Volume/auth_secret.key绑定，别公开。

• 适合谁：需要把下载能力接进自己系统的开发者。

跟着走一个真实任务

任务：批量下载 3 个作品，每个作品单独建文件夹、按作者归类，并保存作品信息。

第 1 步：拿到链接。在浏览器里（或用用户脚本）把 3 个作品链接复制到一段文字里，中间用空格隔开。

第 2 步：运行下载命令。在项目根目录执行：

uv run main.py --url "链接1 链接2 链接3" --folder_mode true --author_archive true --note_format md

--folder_mode true让每个作品独占文件夹，--author_archive true按作者归类，--note_format md把每个作品的标题、描述、互动数据存成 Markdown。

第 3 步：确认落盘位置。默认在Volume/Download下，按"作者ID_作者昵称"分文件夹存放；想换位置就加--work_path "D:\素材"（Windows）或--work_path ./downloads。

第 4 步（可选）：只挑部分图片。某个图文作品只想要第 1、3 张时：

uv run main.py --url "该作品链接" --index "1 3"

注意设置--index后只处理第一个链接。

命令行支持的全部参数用uv run main.py --help查看，效果如下：

跑完这一遍，文件应该在指定文件夹里了。如果只有个别作品没下载下来，别慌，对照下一节排查。

把参数调得更顺手

所有参数都在Volume/settings.json（首次运行自动生成）里，命令行参数也能用--update_settings直接写回配置文件。大多数人只会动下面这几个：

Cookie 的获取方式：打开小红书网页版（登录与否都行）→ 按F12打开开发者工具 → 切到"网络"选项卡 → 过滤框输入cookie-name:web_session→ 点击任意作品 → 选中一个数据包，全选复制 Cookie 后填入程序或配置文件：

其余参数（avg_delay、proxy、chunk、impersonate等）完整说明见 README.md 的配置文件章节，不常用的不用碰。参数调顺之后，如果哪里不对劲，直接进排查环节。

卡住了，对照排查

四个都排过了还不行，带上你的系统和报错信息去仓库提 Issue，比瞎试快。

用得安心，也守得住分寸

几条提醒，都是帮你少惹麻烦：

• 用途边界：下载的内容用于个人学习、研究和备份自己的作品即可，未经作者许可，不要二次传播或商用。
• 请求频率：程序内置了请求延时（avg_delay默认 6 秒），不要刻意把它压到 0 去"提速"；用户脚本的自动滚动功能默认关闭也是同样的原因——自动化操作会带来账号风控风险。
• 凭证保管：Cookie 约等于你的账号凭证，API/MCP 令牌默认永久有效，都不要分享给别人；不用了就去掉。
• 灰色地带别碰：批量抓取、账号相关灰色业务，风险自负，项目作者不为这些行为背书。

用得稳妥了，如果你顺手，还可以让这个项目变得更好一点。

让这个项目更好一点

• 发现问题、有需求：直接在仓库提 Issue，把现象、环境、日志写清楚即可。
• 想改代码：Fork 后基于develop分支开发，提交 PR 时保持提交信息格式<类型>: <简短描述>；不确定的方向，先提 Issue 和作者对齐，避免重复劳动。
• 想帮文档、翻译：同样直接提 PR，项目本身就欢迎这类贡献。
• 想基于它做二次开发：先看仓库里的 example.py，参数和调用方式都有注释。

下次再看到想存下来的作品，不用再对着水印截图发愁——复制链接，敲下那条命令，无水印原文件就会安静地躺在你的素材文件夹里。

【免费下载链接】XHS-Downloader小红书（XiaoHongShu、RedNote）链接提取/作品采集工具项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader