XHS-Downloader 使用指南：从粘贴链接到本地素材库的最短路径
项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader XHS-Downloader 是一款免费开源的小红书下载工具：把笔记链接贴进去，它解析出原图和视频地址，把文件存到你指定的目录。设计师挑原图、收藏党做本地批量备份、开发者接自动化，都适用。笔记链接说失效就失效，它的作用就是在你需要之前，把内容变成硬盘上的文件。
跑起来
读完这节，你照抄三组命令，10 分钟内本地就有第一个下载下来的小红书文件。
前置条件：Python 3.12 及以上。然后按顺序执行：
git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader
cd XHS-Downloader
安装依赖，两种方式任选其一：
pip install -r requirements.txt
uv sync --no-dev
启动程序：
python main.py
不带参数启动的是图形界面：中间一个输入框，提示"请输入小红书图文/视频作品链接"，左右侧栏有任务队列、剪贴板模式、下载记录、运行日志、程序设置。把链接贴进输入框，点"处理任务"。
首次运行你会看到什么：
- 程序在项目根目录自动生成
Volume/文件夹，里面有配置文件 settings.json 和下载记录数据库 ExploreID.db - 图片和视频文件默认落在 Volume/Download/ 目录
- 文件名默认格式为"发布时间 作者昵称 作品标题"，格式字段可在配置里改
- 同一个作品再次提交会被自动跳过，记录由 download_record 开关控制；下载中断后重跑同一命令可断点续传
更多运行方式（Docker、可执行文件）见 README.md。
用起来
读完这节，你可以按使用强度对号入座：轻度贴一条链接就收工，中度挑图、批量加归档，重度把下载能力接进 API、AI 和脚本。
轻度：贴一条链接，直接出结果
命令行最简形式：
python main.py --url "作品链接"
默认行为：
- explore、discovery/item、user/profile 长链接和 xhslink.com 短链都认，多条链接用空格分隔，程序自动提取有效链接
- 图文按 image_format 指定格式落盘，默认 JPEG；视频默认原格式直下
- 已下载过的作品自动跳过，不会重复落盘
中度：只挑要的那几张图，再把链接批量喂进去
命令行里最有用的是 --index：长图文里只要第 3、6、9 张时，不必全量下载：
python main.py --url "作品链接" --index "3 6 9"
注意边界：设置了 --index 时只处理第一个链接；不带 --index 时才支持多链接一次传入。保存目录也可以临时改：
python main.py --url "作品链接" --work_path "D:\素材库"
归档规则由三个开关控制：
| 开关 | 作用 | 默认值 |
|---|---|---|
| folder_mode | 每篇作品单独一个文件夹，文件夹名与文件名一致 | false |
| author_archive | 每个作者一个文件夹，名为 作者ID_作者昵称，作者改昵称会自动更新 | false |
| write_mtime | 文件修改时间同步为作品发布时间 | false |
批量链接走"浏览器提取 + 程序下载"的组合：在 Tampermonkey 里导入仓库自带的 static/XHS-Downloader.js 用户脚本，浏览器里就能提取账号发布、点赞、收藏的作品链接，脚本菜单还支持"推送下载任务"直接发给主程序（需把配置里 script_server 设为 true，主程序保持后台运行）。
提醒一句：脚本的"自动滚动加载"默认关闭，开启后可能被小红书检测为自动化操作，有风控风险，自己权衡。完整参数用 python main.py --help 查看，逻辑在 source/CLI/main.py。
重度：API、MCP、脚本，把下载能力交给别的程序
服务器模式启动后，终端会输出鉴权令牌，调用接口需在请求头携带 Authorization: Bearer <令牌>，不带或无效返回 403。令牌默认永久有效，与 Volume/auth_secret.key 绑定，删掉该文件可换新令牌：
- API 模式：
python main.py api，然后访问http://127.0.0.1:5556/docs看自动生成的交互式文档，POST /xhs/detail传作品链接即可取数并触发下载，支持index挑图、check_record跳过已下载作品 - MCP 模式：
python main.py mcp，需额外安装依赖（pip install "fastmcp>=4.1.0"或uv sync --no-dev --extra mcp），把 MCP URL 配成http://127.0.0.1:5556/mcp并带上鉴权头，AI 助手就能直接下单 - 用户脚本联动：配置 script_server 为
true后，浏览器脚本的"推送下载任务"直达主程序
Docker 运行同样支持 TUI、API、MCP 三种模式（Dockerfile），但不支持读取和监听剪贴板。想直接改代码调用，根目录的 example.py 是一份完整示例。
调起来
读完这节，你只需要做两件事：配一次 Cookie、必要时设一次代理。之后日常基本不动配置。
先说透一句实话：不配置 Cookie，视频只能拿到低分辨率版本；配好之后画质解锁，而且完全无需登录账号。配置步骤：
- 浏览器打开小红书网页版（
https://www.xiaohongshu.com/explore），按 F12 打开开发者工具 - 切到"网络"标签，勾选"保留日志"，选 Fetch/XHR 筛选，点开任意一篇作品
- 选中一个数据包，在请求标头里整段复制 Cookie 字段，粘到程序设置界面或
settings.json的 cookie 字段，重启程序生效
配置文件在 Volume/settings.json，首次运行自动生成；界面操作不顺手时直接编辑这个 JSON，改完重启生效。参数定义见 source/module/settings.py。
高频参数速查：
| 参数 | 作用 | 默认值 |
|---|---|---|
| work_path | 作品保存根路径 | 项目根目录/Volume |
| folder_name | 作品存放文件夹名 | Download |
| image_format | 图片格式，AUTO/PNG/WEBP/JPEG/HEIC | JPEG |
| live_download | LivePhoto 动图下载开关 | false |
| video_preference | 视频偏好：resolution / bitrate / size | resolution |
| folder_mode | 每篇作品单独文件夹 | false |
| author_archive | 每个作者单独文件夹 | false |
| download_record | 记录已下载作品 ID，自动跳过重复 | true |
| write_mtime | 文件修改时间同步为发布时间 | false |
| proxy | 网络代理，proxy_download 控制下载文件时是否走代理 | 无 |
完整参数表以 README.md 的配置文件章节和 python main.py --help 为准。
修起来
读完这节，遇到最常见的问题可以按"现象 → 原因 → 动作"直接处理，不用翻长文档。
| 现象 | 原因 | 动作 |
|---|---|---|
| 下载卡住或报错 | 全局代理干扰了请求 | 关闭全局代理后重试，再看运行日志定位 |
| 视频清晰度低 | 未配置 Cookie | 按"调起来"三步配好，重启程序重新下载 |
| 链接提示失效 | 作品链接自带日期信息，旧链接易被风控拦截 | 重新复制最新链接再提交，保持内置的请求延时默认值 |
| 同一作品反复提交被跳过 | download_record 默认开启，作品 ID 已入库 | 属正常去重；要重下就删掉 ExploreID.db 里对应的 ID |
收尾说一句：收藏夹里那些怕哪天打不开的笔记，真的不想变成硬盘里的永久文件吗？现在打开终端，python main.py，把第一条链接贴进输入框——10 分钟后你就能去 Volume/Download/ 里验收结果。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
