📑 项目功能
项目程序与用户脚本功能清单，快速了解项目能力（点击展开）
程序功能
- ✅ 采集小红书作品信息
- ✅ 提取小红书作品下载地址
- ✅ 下载小红书作品文件
- ✅ 下载视频作品封面文件
- ✅ 下载小红书 livePhoto 文件
- ✅ 自动跳过已下载的作品文件
- ✅ 作品文件完整性处理机制
- ✅ 自定义图文作品文件下载格式
- ✅ 持久化储存作品信息至文件
- ✅ 作品文件储存至单独文件夹
- ✅ 后台监听剪贴板下载作品
- ✅ 记录已下载作品 ID
- ✅ 支持命令行下载作品文件
- ☑️ 从浏览器读取 Cookie
- ✅ 自定义文件名称格式
- ✅ 支持 API 调用功能
- ✅ 支持 MCP 调用功能
- ✅ 支持文件断点续传下载
- ✅ 智能识别作品文件类型
- ✅ 支持设置作者备注
- ✅ 自动更新作者昵称
脚本功能
- ✅ 下载小红书作品文件
- ✅ 提取推荐页面作品链接
- ✅ 提取账号发布作品链接
- ✅ 提取账号收藏作品链接
- ✅ 提取账号点赞作品链接
- ✅ 提取账号专辑作品链接
- ✅ 提取搜索结果作品链接
- ✅ 提取搜索结果用户链接
📸 程序截图
前往 bilibili 观看演示；前往 YouTube 观看演示
GUI 界面截图
TUI 界面截图（模式命令：python .\main.py TUI）
🔗 支持链接
🥣 使用方法
如果仅需下载作品文件，建议选择 程序运行 或 Docker 运行；如果有其他需求，建议选择 源码运行！
⚠️ Cookie 配置为非强制项；如遇功能异常，建议配置或更新 Cookie 后再次尝试！
⚠️ 未设置 Cookie 时，视频作品只能下载低分辨率文件；建议配置 Cookie 以获取更高画质（无需登录账号）！
🖱 程序运行
⭐ Mac OS、Windows 10 及以上用户可前往 Releases 或者 Actions 下载程序压缩包，解压后打开程序文件夹，双击运行 main 即可使用。
⭐ 本项目包含自动构建可执行文件的 GitHub Actions，使用者可以随时使用 GitHub Actions 将最新源码构建为可执行文件！
⭐ 自动构建可执行文件教程请查阅本文档的 构建可执行文件指南 部分；如果需要更加详细的图文教程，请 查阅文章！
注意：由于 Mac OS 平台的可执行文件 main 未经过代码签名，首次运行时会受到系统安全限制。请先在终端执行 xattr -cr 项目文件夹路径 命令移除安全标记，执行一次后即可正常运行。
若通过此方式使用程序，文件默认下载路径为：.\Volume\Download；配置文件路径为：.\Volume\settings.json
程序更新
方案一：下载并解压文件，将旧版本的 Volume 文件夹复制到新版本的程序根目录。
方案二：下载并解压文件（不要运行程序），复制全部文件，直接覆盖旧版本文件。
⌨️ 源码运行
- 安装不低于
3.12 版本的 Python 解释器
- 下载最新的源码或 Releases 发布的源码至本地
使用 pip 安装项目依赖
- 运行
python -m venv venv 命令创建虚拟环境（可选）
- 运行
.\venv\Scripts\activate.ps1 或者 venv\Scripts\activate 命令激活虚拟环境（可选）
- 运行
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt 命令安装程序所需模块
- 运行
python .\main.py 或者 python main.py 命令启动 XHS-Downloader
使用 uv 安装项目依赖（推荐）
- 运行
uv sync --no-dev 命令同步环境依赖
- 运行
uv run main.py 命令启动 XHS-Downloader
⌨️ Docker 运行
- 获取镜像
- 方式一：使用
Dockerfile 文件构建镜像
- 方式二：使用
docker pull joeanamier/xhs-downloader 命令拉取镜像
- 方式三：使用
docker pull ghcr.io/joeanamier/xhs-downloader 命令拉取镜像
- 创建容器
- TUI 模式：
docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it <镜像名称>
- API 模式：
docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it <镜像名称> python main.py api
- MCP 模式：
docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it <镜像名称> python main.py mcp
注意：此处的 <镜像名称> 需与您在第一步中使用的镜像名称保持一致（joeanamier/xhs-downloader 或 ghcr.io/joeanamier/xhs-downloader）
- 运行容器
- 启动容器：
docker start -i 容器名称/容器 ID
- 重启容器：
docker restart -i 容器名称/容器 ID
Docker 运行项目时不支持 命令行调用模式，无法使用 读取剪贴板 与 监听剪贴板 功能，可以正常粘贴内容，其他功能如有异常请反馈！
🛠 命令行模式
命令行模式说明，适合习惯命令行操作或需要脚本化调用的用户（点击展开）
项目支持命令行运行模式，可通过命令行参数直接下载作品文件，也可以设置需要下载的图片序号！
注意：未设置 --index 参数时，支持传入多个作品链接，全部链接需要使用引号包围，链接之间使用空格分隔；已设置 --index 参数时，不支持传入多个作品链接，即使传入多个作品链接，程序仅处理首个作品链接！
bool 类型参数支持使用 true、false、1、0、yes、no、on 或 off（不区分大小写）来设置。
从浏览器读取 Cookie
该功能已失效，请参考 获取 Cookie 教程！
可以使用命令行实现 从浏览器读取 Cookie 并写入配置文件！
命令示例：python .\main.py --browser_cookie Chrome --update_settings
兼容性提醒：此功能依赖的第三方模块已长期未更新，可能无法正常支持最新浏览器版本。若功能出现异常，请尝试手动获取 Cookie！
🖥 服务器模式
服务器模式包含 API 模式和 MCP 模式！
API 模式
API 模式说明，适合需要调用接口获取作品数据或下载文件的开发者（点击展开）
启动：运行命令：python .\main.py api
关闭：按下 Ctrl + C 关闭服务器
访问 http://127.0.0.1:5556/docs 或者 http://127.0.0.1:5556/redoc；你会看到自动生成的交互式 API 文档！
请求接口：/xhs/detail
请求方法：POST
请求格式：JSON
请求参数：
| 参数 |
类型 |
含义 |
默认值 |
| url |
str |
小红书作品链接，自动提取，不支持多链接；必需参数 |
无 |
| download |
bool |
是否下载作品文件；设置为 true 将会耗费更多时间；可选参数 |
false |
| index |
list[int] |
下载指定序号的图片文件，仅对图文作品生效；download 参数设置为 false 时不生效；可选参数 |
null |
| cookie |
str |
请求数据时使用的 Cookie；可选参数 |
配置文件 cookie 参数 |
| proxy |
str |
请求数据时使用的代理；可选参数 |
配置文件 proxy 参数 |
| check_record |
bool |
是否跳过已有下载记录的作品；可选参数 |
true |
代码示例：
async def example_api():
"""通过 API 设置参数，适合二次开发"""
server = "http://127.0.0.1:5556/xhs/detail"
data = {
"url": "", # 必需参数
"download": True,
"index": [
3,
6,
9,
],
"proxy": "http://127.0.0.1:10808",
}
response = post(server, json=data, timeout=10)
print(response.json())
MCP 模式
MCP 模式说明，适合需要启动 MCP 服务接入 AI 助手等工具的开发者（点击展开）
启动：运行命令：python .\main.py mcp
关闭：按下 Ctrl + C 关闭服务器
MCP 配置示例
Streamable HTTP
MCP URL：http://127.0.0.1:5556/mcp/
MCP 调用示例
获取小红书作品信息
下载小红书作品文件
下载图文作品时可以指定需要下载的图片序号；默认不返回作品信息，如需返回作品信息，请在对话时明确表述。
📜 其他说明
- 由于作品链接携带日期信息，使用先前日期获取的作品链接可能会被风控，建议下载作品文件时使用最新获取的作品链接
- 如果需要程序使用代理请求数据，请在配置文件
settings.json 设置 proxy 参数
Windows 系统需要以管理员身份运行程序才能读取 Chromium、Chrome、Edge 浏览器 Cookie- 如果开启保存作品数据至文件功能，作品数据默认储存至
./Volume/Download/ExploreData.db 文件
- 程序下载记录数据储存至
./Volume/ExploreID.db 文件
- 为了避免请求频率过高对平台服务器造成影响，本项目内置请求延时机制
🕹 用户脚本
如果您的浏览器安装了 Tampermonkey 浏览器扩展程序，可以使用用户脚本体验项目功能！
用户脚本链接（右键单击复制链接）：master 分支、develop 分支
查看 Tampermonkey 用户脚本截图（点击展开）
提示：使用 XHS-Downloader 用户脚本批量提取作品链接，搭配 XHS-Downloader 程序可以实现批量下载作品文件！
修改用户脚本语言
🌏 连接服务器
⭐ 本项目支持通过浏览器用户脚本与主程序联动，实现一键推送下载任务。
功能说明：
- 在项目程序的配置文件中，需要将
script_server 参数设置为 true
- 保持项目程序在后台运行，它将作为服务器，接收用户脚本的指令（TUI、MCP 和 API 模式均支持）
- 当您在浏览器中访问作品页面时，点击用户脚本菜单中的
推送下载任务 选项
- 用户脚本会将下载任务发送给项目程序，由项目程序负责处理和下载文件
📜 脚本说明
- 下载小红书作品文件时，脚本需要花费时间处理文件，请等待片刻，请勿多次点击下载按钮
- 提取账号发布、收藏、点赞、专辑作品链接时，脚本可以自动滚动页面直至加载全部作品
- 提取推荐作品链接、搜索作品、用户链接时，脚本可以自动滚动指定次数加载更多内容，默认滚动次数：50 次
- 自动滚动页面功能默认关闭；用户可以自由开启，并修改滚动页面次数，修改后立即生效
- 如果未开启自动滚动页面功能，用户需要手动滚动页面以便加载更多内容后再进行其他操作
- 支持作品文件打包下载；该功能默认开启，多个文件的作品将会以压缩包格式下载
- 向服务器推送下载任务时，文件格式、名称规则等设置以服务器配置文件中的设置为准
- 使用全局代理工具可能会导致脚本下载文件失败，如有异常，请尝试关闭代理工具，必要时向作者反馈
- XHS-Downloader 用户脚本仅实现可见即可得的数据采集功能，无任何收费功能和破解功能
自动滚动页面功能代码已重构，该功能默认关闭！启用该功能可能会被小红书检测为自动化操作，从而导致账号受到风控或封禁风险！
💻 二次开发
二次开发代码示例，适合基于项目进行二次开发的开发者（点击展开）
如果有其他需求，可以根据 example.py 的注释提示进行代码调用或修改！
async def example():
"""通过代码设置参数，适合二次开发"""
# 示例链接
demo_link = "https://www.xiaohongshu.com/explore/XXX?xsec_token=XXX"
# 实例对象
work_path = "D:\\" # 作品数据/文件保存根路径，默认值：项目根路径
folder_name = "Download" # 作品文件储存文件夹名称（自动创建），默认值：Download
name_format = "作品标题 作品描述"
impersonate = "chrome146" # 浏览器模拟目标
cookie = "" # 小红书网页版 Cookie
proxy = None # 网络代理
proxy_download = False # 下载文件时，是否使用 proxy 参数的网络代理
timeout = 5 # 请求数据超时限制，单位：秒
chunk = 1024 * 1024 * 10 # 下载文件时，每次从服务器获取的数据块大小，单位：字节
max_retry = 2 # 请求数据失败时，重试的最大次数，单位：次
record_data = False # 是否保存作品数据至文件
image_format = "WEBP" # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
folder_mode = False # 是否将每个作品的文件储存至单独的文件夹
image_download = True # 图文、图集作品文件下载开关
video_download = True # 视频作品文件下载开关
video_cover_download = False # 视频作品封面文件下载开关
live_download = False # 图文动图文件下载开关
download_record = True # 是否记录下载成功的作品 ID
language = "zh_CN" # 设置程序提示语言
author_archive = True # 是否将每个作者的作品存至单独的文件夹
write_mtime = True # 是否将作品文件的 修改时间 修改为作品的发布时间
note_format = "" # 作品信息保存格式，支持：txt、md、all，为空则不保存
# read_cookie = None # 读取浏览器 Cookie，支持设置浏览器名称（字符串）或者浏览器序号（整数），设置为 None 代表不读取
# async with XHS() as xhs:
# pass # 使用默认参数
async with XHS(
work_path=work_path,
folder_name=folder_name,
name_format=name_format,
impersonate=impersonate,
cookie=cookie,
proxy=proxy,
proxy_download=proxy_download,
timeout=timeout,
chunk=chunk,
max_retry=max_retry,
record_data=record_data,
image_format=image_format,
folder_mode=folder_mode,
image_download=image_download,
video_download=video_download,
video_cover_download=video_cover_download,
live_download=live_download,
download_record=download_record,
language=language,
# read_cookie=read_cookie,
author_archive=author_archive,
write_mtime=write_mtime,
note_format=note_format,
) as xhs: # 使用自定义参数
download = True # 是否下载作品文件，默认值：False
# 返回作品详细信息，包括下载地址
# 获取数据失败时返回空字典
print(
await xhs.extract(
demo_link,
download,
index=[
1,
2,
5,
],
)
)
📋 读取剪贴板
读取剪贴板平台说明，适合 Windows 以外的用户（Mac / Linux）（点击展开）
项目使用 pyperclip 实现读取剪贴板功能，该模块在不同的系统上会有差异。
在 Windows 上，不需要额外的模块。
在 Mac 上，该模块使用 pbcopy 和 pbpaste 命令，这些命令应该随操作系统一起提供。
在 Linux 上，该模块使用 xclip 或 xsel 命令，这些命令应该随操作系统一起提供。否则，请运行 "sudo apt-get install xclip" 或 "sudo apt-get install xsel"（注意：xsel 似乎并不总是有效）
在其他 Linux 系统上，你需要安装 qtpy 或 PyQT5 模块。
⚙️ 配置文件
配置文件参数说明，适合需要直接修改程序配置参数的用户（点击展开）
项目根目录下的 ./Volume/settings.json 文件，首次运行自动生成，可以自定义程序运行参数；如果设置了无效的参数值，程序将会使用参数默认值！
如果您在程序界面修改配置时无法正常交互，可以直接编辑配置文件；如果您的计算机没有合适的程序编辑 JSON 文件，建议使用 在线工具 编辑配置文件内容，修改后需要重启软件才能生效。
| 参数 |
类型 |
含义 |
默认值 |
| mapping_data |
str: str |
#作者别名映射表，格式：作者ID: 作者别名 |
无 |
| work_path |
str |
作品数据 / 文件保存根路径 |
项目根路径/Volume |
| folder_name |
str |
作品文件储存文件夹名称 |
Download |
| name_format |
str |
作品文件名称格式，字段之间使用空格分隔，支持字段：收藏数量、评论数量、分享数量、点赞数量、作品标签、作品ID、作品标题、作品描述、作品类型、发布时间、最后更新时间、作者昵称、作者ID |
发布时间 作者昵称 作品标题 |
| impersonate |
str |
浏览器模拟目标；参考 curl_cffi 文档 |
chrome146 |
| cookie |
str |
小红书网页版 Cookie，无需登录，非必需参数！ |
无 |
| proxy |
str |
设置程序代理 |
null |
| proxy_download |
bool |
下载文件时，是否使用 proxy 参数的网络代理 |
false |
| timeout |
int |
请求数据超时限制，单位：秒 |
10 |
| chunk |
int |
下载文件时，每次从服务器获取的数据块大小，单位：字节 |
2097152(2 MB) |
| max_retry |
int |
请求数据失败时，重试的最大次数，单位：秒 |
5 |
| record_data |
bool |
是否保存作品数据至 SQLite 数据库（所有作品统一保存） |
false |
| image_format |
str |
图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
部分作品没有 HEIC 格式的文件，此时下载的文件可能为 WEBP 格式！
设置为 AUTO 时表示动态格式，实际格式取决于服务器响应数据！ |
JPEG |
| image_download |
bool |
图文、图集作品文件下载开关 |
true |
| video_download |
bool |
视频作品文件下载开关 |
true |
| video_cover_download |
bool |
视频作品封面下载开关；封面格式与图文作品文件格式一致 |
false |
| live_download |
bool |
图文动图文件下载开关 |
false |
| video_preference |
str |
视频作品文件下载偏好；含义：resolution：分辨率优先；bitrate：码率优先；size：文件大小优先 |
resolution |
| folder_mode |
bool |
是否将每个作品的文件储存至单独的文件夹；文件夹名称与文件名称保持一致 |
false |
| download_record |
bool |
是否记录下载成功的作品 ID，如果开启，程序将会自动跳过下载存在记录的作品 |
true |
| author_archive |
bool |
#是否将每个作者的作品储存至单独的文件夹；文件夹名称为 作者ID_作者昵称 |
false |
| write_mtime |
bool |
是否将作品文件的 修改时间 属性修改为作品的发布时间 |
false |
| language |
str |
设置程序语言，目前支持：zh_CN、en_US |
XHS-Downloader 是一款工具，可以从小红书（XiaoHongShu / RedNote）提取分享链接，并下载帖子中的内容，包括图片、视频、实况照片和封面。