XHS-Downloader

XHS-Downloader 简体中文 | English 🔥 小红书（XiaoHongShu、RedNote）链接提取/作品采集工具！ 📑 项目功能 项目程序与用户脚本功能清单，快速了解项目能力（点击展开） 程序功能 ✅ 采集小红书作品信息 ✅ 提取小红书作品下载地址 ✅ 下载小红书作品文件 ✅ 下载视频作品封面文件 ✅ 下载小红书 livePhoto 文件 ✅ 自动跳过已下载的作品文件 ✅ 作品文件完整性处理机制 ✅ 自定义图文作品文件下载格式 ✅ 持久化储存作品信息至文件 ✅ 作品文件储存至单独文件夹 ✅ 后台监听剪贴板下载作品 ✅ 记录已下载作品 ID ✅ 支持命令行下载作品文件 ☑️ 从浏览器读取 Cookie ✅ 自定义文件名称格式 ✅ 支持 API 调用功能 ✅ 支持 MCP 调用功能 ✅ 支持 API、MCP 和用户脚本鉴权 ✅ 支持文件断点续传下载 ✅ 智能识别作品文件类型 ✅ 支持设置作者备注 ✅ 自动更新作者昵称 脚本功能 ✅ 下载小红书作品文件 ✅ 提取推荐页面作品链接 ✅ 提取账号发布作品链接 ✅ 提取账号收藏作品链接 ✅ 提取账号点赞作品链接 ✅ 提取账号专辑作品链接 ✅ 提取搜索结果作品链接 ✅ 提取搜索结果用户链接 📸 程序截图 前往 bilibili 观看演示；前往 YouTube 观看演示 GUI 界面截图 TUI 界面截图（模式命令：python .\main.py TUI） 🔗 支持链接 https://www.xiaohongshu.com/explore/作品ID?xsec_token=XXX https://www.xiaohongshu.com/discovery/item/作品ID?xsec_token=XXX https://www.xiaohongshu.com/user/profile/作者ID/作品ID?xsec_token=XXX https://xhslink.com/分享码 支持单次输入多个作品链接，链接之间使用空格分隔；程序会自动提取有效链接，无需额外处理！ 🥣 使用方法 如果仅需下载作品文件，建议选择 程序运行 或 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（不区分大小写）来设置。 生成鉴权令牌 python .\main.py token 使用 uv 时可以运行 uv run main.py token 获取鉴权令牌。 从浏览器读取 Cookie 该功能已失效，请参考 获取 Cookie 教程！ 可以使用命令行实现 从浏览器读取 Cookie 并写入配置文件！ 命令示例：python .\main.py --browser_cookie Chrome --update_settings 兼容性提醒：此功能依赖的第三方模块已长期未更新，可能无法正常支持最新浏览器版本。若功能出现异常，请尝试手动获取 Cookie！ 🖥 服务器模式 服务器模式包含 API 模式和 MCP 模式！ 鉴权令牌 API 和 MCP 模式启动时会在终端输出鉴权令牌。 令牌默认永久有效，请勿公开。令牌与当前项目的 Volume/auth_secret.key 文件绑定；如需更换令牌，可以删除该文件，程序下次启动或生成令牌时会自动创建新的密钥，旧令牌随即失效。 API 模式 API 模式说明，适合需要调用接口获取作品数据或下载文件的开发者（点击展开） 启动：运行命令：python .\main.py api 关闭：按下 Ctrl + C 关闭服务器 调用业务接口时必须在请求头中携带 Authorization: Bearer <令牌>，未携带或令牌无效时返回 403。在 /docs 页面中点击右上角 Authorize，输入令牌即可调试接口。 访问 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 是否跳过已有下载记录的作品；可选参数