小红书下载工具 XHS-Downloader 完整教程：5 分钟把收藏的笔记变成本地文件

小红书下载工具 XHS-Downloader 完整教程：5 分钟把收藏的笔记变成本地文件

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

打开收藏夹，137 条笔记躺在里面，你想把它们全部存到本地——逐条右键另存，存到第三张图你就想摔键盘。小红书下载工具 XHS-Downloader 就是来解决这件事的开源项目：批量收链接、解析作品信息、下载文件这三步它全包了。读完这篇文章，你能把任意一条小红书链接变成下载文件夹里整理好的图片、视频和 livePhoto（就是小红书里那种会动的图）。

它到底能替你做什么

先搞清楚它的能力边界，你才知道往哪用。核心能力压缩成三件麻烦事：

• 收链接：账号的发布、收藏、点赞、专辑作品，搜索结果和推荐页里的作品，都能一键批量提取（由浏览器用户脚本完成，结果直接进剪贴板，不用逐条复制）。
• 取信息：拿到链接后自动解析作品标题、作者、发布时间，以及图片和视频的真实下载地址（这一步你完全不用管，程序后台就做了）。
• 落文件：按你设定的格式下载图片、视频、livePhoto，支持断点续传、自动跳过已下载的作品、按作者建文件夹归档（以前手动三四步，现在粘贴链接就行）。

它不做的事也清楚：不负责登录态的账号操作，不做内容二创，只干"链接 → 文件"这一件事。

装好 → 跑起来 → 下到第一个文件

这一节的目标只有一个：让程序在你电脑上转起来，并下到第一个文件。源码运行是最快的路，下面四行命令依次完成下载代码、进目录、装依赖、启动程序（需要 Python 3.12 或更高版本）：

git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader cd XHS-Downloader pip install -r requirements.txt python main.py

启动后你看到的不是命令行黑框，而是一个 TUI 界面——长得像图形软件、操作全靠键盘的那种。主界面正中是一个输入框，把小红书链接粘进去（多个链接用空格隔开，程序会自动清洗出有效链接），然后按"下载作品文件"按钮，下方的日志区就开始滚动输出解析和下载进度。

界面底部还有几个快捷键值得现在就记一下：S进设置、R看下载记录、M开启剪贴板监听——开启后你在任何地方复制一条小红书链接，程序都会自动开始下载，连粘贴都省了。习惯用 uv 管理依赖的话，后两条命令换成uv sync --no-dev和uv run main.py即可；习惯 Docker 的话，一行docker pull joeanamier/xhs-downloader拉取镜像后docker run -p 5556:5556也能起。

日常最高频的那条路：脚本圈链接 + 主程序下载

日常刷到素材想囤，最高频的组合是"浏览器脚本负责圈链接，TUI 主程序负责下载"。项目里自带一个 Tampermonkey 用户脚本（用户脚本源码），装上之后小红书页面侧边会多出一个功能菜单。

安装分三步：给浏览器装好 Tampermonkey 扩展；新建脚本，把项目里static/XHS-Downloader.js的内容整段粘进去保存；刷新小红书页面，菜单就出来了。

菜单能做的事比你想的多：提取账号发布 / 收藏 / 点赞 / 专辑的作品链接、提取搜索结果的作品和用户链接、提取推荐页的作品链接，还能一键把下载任务推送给本地主程序（需要先开联动，见下文）。提取结果自动写入剪贴板——逛一圈页面，几十上百条链接就已经躺在剪贴板里了，切回主程序直接粘贴下载。

这里有个容易卡住的细节：脚本默认不自动滚动页面，你得自己手动往下滑、把内容加载出来之后再点提取。设置菜单里可以打开自动滚动并指定次数（默认 50 次），但官方明确提醒过：启用该功能可能被小红书判定为自动化操作，有账号风控甚至封号风险。我的建议是批量提取这种低频操作，手动滚一滚最稳妥。

想更省事可以开联动：在主程序配置文件里把script_server设为true，保持主程序后台运行，浏览器菜单点"推送下载任务"，链接就直接送到主程序手里下载，全程不用切窗口。文件格式、命名规则以主程序的配置为准。

想更快？把重复劳动交给命令

当你明确知道自己要下载哪一批作品时，命令行模式（CLI）是效率最高的入口——主程序的所有设置都变成了命令参数，python main.py --help一敲，帮助面板里每个参数的作用一目了然。

下载单条作品，一条命令：

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

多条一起下、只挑某几张图，把链接用空格隔开、序号也空格隔开，整体加引号：

python main.py --url "链接1 链接2 链接3" --index "1 3 5"

最常用参数速查：

参数	作用	什么时候用
--url/-u	指定作品链接，多个用空格分隔	每次下载都用的基础参数
--index/-i	只下载指定序号的图片	长图集只要精选几张时
--image_format/-if	指定图片格式（PNG/WEBP/JPEG/HEIC/AUTO）	不想收到 HEIC/WEBP 打不开的文件时
--folder_mode/-fm	每个作品存进独立文件夹	单个作品文件多、想分门别类时
--author_archive/-aa	按作者归档	长期追更某几个博主时
--update_settings/-us	把本次参数写回配置文件	试出顺手的参数组合、想固化下来时

--update_settings是对进阶用户最友好的一个参数：你可以在命令行里反复试参数组合，试到顺手的那次，命令末尾加上它，整套参数就被写回配置文件，之后所有模式都沿用。这相当于把调参过程变成了可复现的命令，而不是打开 JSON 文件盲改。

让它变成别人能调的零件

前面都是"你指挥机器"，这一节反过来：让别的程序来指挥它。做内容运营、写自动化脚本、或者搭 AI 工作流，会在这里找到价值。

API 模式一条命令启动，服务默认跑在http://127.0.0.1:5556，浏览器打开/docs就是自动生成的交互式文档：

python main.py api

核心接口是POST /xhs/detail，传一个 JSON 就能取作品信息或触发下载。接法很简单：

import httpx resp = httpx.post( "http://127.0.0.1:5556/xhs/detail", json={"url": "作品链接", "download": True, "index": [1, 3, 5], "skip": False}, timeout=60, ) print(resp.json())

接完之后你不用再自己解析小红书接口了：cookie和proxy参数缺省时自动沿用配置文件里的值，你的公众号机器人、定时任务脚本直接复用这套采集能力。

MCP 模式则是给 AI 助手准备的：启动python main.py mcp后，在支持 MCP 的客户端里配置一个 Streamable HTTP 服务，地址填http://127.0.0.1:5556/mcp/，AI 就能用自然语言指挥它获取作品数据或下载文件——在对话框里直接说"把这个链接的图文下下来，只要第 1、3、5 张"即可。

这套能力的意义在于：下载不再是孤立的操作，而是可以嵌进任何工作流的零件。

这几个参数不调，后面会反复踩坑

参数再全，真正值得动手的也就几个。所有模式的设置最终都汇总到Volume/settings.json（首次运行自动生成），不想碰 JSON 的话，TUI 主界面按S键进设置界面，效果一样。下面是我认为最该调的 8 个：

参数	默认值	什么时候该改它
image_format	JPEG	想接近原图质量就设AUTO（跟随服务器返回格式）；部分作品没有 HEIC 版本时会自动降级为 WEBP
name_format	发布时间 作者昵称 作品标题	想按自己习惯归档时，可换入点赞数、作品ID 等字段，空格分隔
folder_mode	false	单个作品文件多、想给它单独一个文件夹时打开
author_archive	false	按作者建文件夹，文件夹名是"作者ID_作者昵称"，作者改昵称时程序会自动同步更新
download_record	true	文件被误删想重下时，清理Volume/ExploreID.db里对应记录；想"文件没了就重下"就临时关掉它
write_mtime	false	想让文件的"修改时间"等于作品发布时间、方便按时间排序时打开
video_preference	resolution	视频选哪种：分辨率优先 / 码率优先 / 体积优先，按你的存储条件定
cookie	空	视频想要高画质时必配（下一节细说），不需要登录账号

author_archive还有个进阶玩法：配合mapping_data参数给作者设别名，归档文件夹就会用你起的别名而不是原始 ID——追更博主、整理竞品素材时很好用。

卡住了？大概率是这几个原因

参数再对，也架不住几个经典坑。下面三个我周围的人都踩过，直接给解法。

为什么下载回来的视频只有标清？

因为没配置 Cookie。未配置时视频作品只能拿到低分辨率版本。解法不需要登录账号：浏览器打开小红书任意页面，按 F12 打开开发者工具，在"网络"面板里过滤web_session，从任意请求里复制完整的 Cookie，填进配置文件的cookie字段即可。

为什么明明没下载过，程序却直接跳过了？

大概率是下载记录在作祟。程序默认把下载成功的作品 ID 存在Volume/ExploreID.db，只要记录里有这个 ID，即使文件已经被你删了，也会被当作"已下载"跳过。想重下就去数据库里删掉对应记录；或者把download_record临时关掉，程序会改为检查文件是否存在。

为什么链接经常报错、请求失败？

两个常见原因：一是作品链接携带日期信息，用很久之前获取的链接可能触发风控，所以尽量用最新提取的链接下载；二是网络环境问题。程序内置了请求延时和重试机制，你再把配置里的max_retry（重试次数，默认 5）和timeout（超时秒数，默认 10）调大，网络特殊的话设置proxy代理。先调这两个参数，比反复重启程序有效得多。

下一步

给你三个可以立刻动手的事：

1. 先跑通一次最小流程，下载五六个作品，确认图片、视频、文件命名都符合预期；
2. 打开设置界面（或settings.json），把image_format、folder_mode、author_archive按自己的归档习惯调一遍；
3. 挑一个重复性场景（比如每周整理某个博主的更新），写成命令行加--update_settings固化下来。

想继续深入，项目根目录的 README.md 是完整中文说明，example.py 里有XHS类的二次开发调用示例，是把下载能力嵌进你自己脚本的起点，用户脚本源码在 static/XHS-Downloader.js。先跑起来，再谈优化——收藏夹里的几百条笔记，不会自己跑进硬盘。

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