XHS-Downloader：小红书作品采集工具

本文介绍 XHS-Downloader，一款功能强大的小红书作品采集工具。该项目支持提取账号发布、收藏、点赞、专辑作品链接，采集作品信息，提取下载地址，以及下载作品文件，是小红书内容创作者和数据分析师的实用工具。

项目简介

XHS-Downloader 是一个开源的小红书数据采集工具，由 JoeanAmier 开发。截至目前，该项目在 GitHub 上已获得 10.1k stars，是小红书数据采集领域最受欢迎的解决方案之一。

该工具支持多种运行模式（TUI、API、MCP），提供完整的功能链：从链接提取、信息采集到文件下载，满足用户的多样化需求。

核心特性

链接提取

• 提取账号发布的作品链接
• 提取账号收藏的作品链接
• 提取账号点赞的作品链接
• 提取专辑作品链接
• 提取搜索结果作品链接
• 提取搜索结果用户链接

信息采集

• 采集小红书作品详细信息
• 提取作品下载地址
• 支持图文、视频等多种作品类型

文件下载

• 下载小红书作品文件
• 支持批量下载
• 自动组织文件目录结构

运行模式

• TUI 模式：终端用户界面，交互式操作
• API 模式：提供 HTTP API 接口
• MCP 模式：支持 Model Context Protocol
• 命令行模式：支持命令行参数调用

技术栈

• Python 3.12+ - 编程语言
• Textual - TUI 界面框架
• FastAPI - API 框架（API 模式）
• Docker - 容器化部署
• GitHub Actions - 自动构建

安装指南

方式一：程序运行（推荐）

macOS / Windows 10+

1. 前往 Releases 或 Actions 下载程序压缩包
2. 解压后打开程序文件夹
3. 双击运行 main 即可使用

macOS 首次运行注意事项：

由于未经过代码签名，首次运行时需要执行：

xattr -cr 项目文件夹路径

方式二：Docker 运行

# 拉取镜像
docker pull joeanamier/xhs-downloader

# TUI 模式运行
docker run --name xhs -p 5556:5556 -v xhs_volume:/app/Volume -it joeanamier/xhs-downloader

# API 模式运行
docker run --name xhs -p 5556:5556 -v xhs_volume:/app/Volume -it joeanamier/xhs-downloader python main.py api

# MCP 模式运行
docker run --name xhs -p 5556:5556 -v xhs_volume:/app/Volume -it joeanamier/xhs-downloader python main.py mcp

方式三：源码运行

使用 pip：

# 克隆仓库
git clone https://github.com/JoeanAmier/XHS-Downloader.git
cd XHS-Downloader

# 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 运行
python main.py

使用 uv（推荐）：

# 同步环境依赖
uv sync --no-dev

# 运行
uv run main.py

快速开始

TUI 模式

1. 运行程序后，进入终端交互界面
2. 粘贴小红书作品链接
3. 选择操作类型（提取信息/下载文件）
4. 等待处理完成

API 模式

# 启动 API 服务
python main.py api

# 调用 API 提取作品信息
curl -X POST http://localhost:5556/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.xiaohongshu.com/explore/作品ID"}'

命令行模式

# 下载指定作品
python main.py download --url "https://www.xiaohongshu.com/explore/作品ID"

# 提取账号作品
python main.py extract --user "作者ID" --type posts

支持的链接格式

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/分享码

支持单次输入多个链接，使用空格分隔，程序会自动提取有效链接。

Cookie 配置

重要提示：未设置 Cookie 时，视频作品只能下载低分辨率文件。建议配置 Cookie 以获取更高画质（无需登录账号）。

配置方法：

1. 打开小红书网页版
2. 登录账号（或保持未登录状态）
3. 打开浏览器开发者工具（F12）
4. 刷新页面，在 Network 中复制 Cookie
5. 将 Cookie 粘贴到程序配置中

文件下载路径

• 程序运行：.\_internal\Volume\Download
• 配置文件：.\_internal\Volume\settings.json
• Docker 运行：/app/Volume

程序更新

方案一：

1. 下载并解压新版本
2. 将旧版本的 _internal\Volume 文件夹复制到新版本的 _internal 文件夹

方案二：

1. 下载并解压新版本（不要运行）
2. 复制全部文件，直接覆盖旧版本文件

注意事项

• 推荐使用 Windows 终端 运行程序以获得最佳显示效果
• Docker 运行时不支持命令行调用模式，无法使用「读取剪贴板」与「监听剪贴板」功能
• 频繁请求可能导致 IP 被限制，建议合理控制请求频率
• 请遵守小红书平台规则和相关法律法规

构建可执行文件

项目包含自动构建 GitHub Actions，可随时将最新源码构建为可执行文件：

1. Fork 本仓库
2. 进入 Actions 页面
3. 选择 Build 工作流
4. 点击 Run workflow

详细教程请参考构建指南。

项目链接

• GitHub 仓库：https://github.com/JoeanAmier/XHS-Downloader
• 下载地址：https://github.com/JoeanAmier/XHS-Downloader/releases
• 演示视频：bilibili | YouTube
• 问题反馈：https://github.com/JoeanAmier/XHS-Downloader/issues