XHS-Downloader

简体中文 | English

🔥 小红书（XiaoHongShu、RedNote）链接提取/作品采集工具！

📑 项目功能

📸 程序截图

前往 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 文件夹复制到新版本的程序根目录。

方案二：下载并解压文件（不要运行程序），复制全部文件，直接覆盖旧版本文件。

⌨️ 源码运行

1. 安装不低于 3.12 版本的 Python 解释器
2. 下载最新的源码或 Releases 发布的源码至本地
使用 pip 安装项目依赖
1. 运行 python -m venv venv 命令创建虚拟环境（可选）
2. 运行 .\venv\Scripts\activate.ps1 或者 venv\Scripts\activate 命令激活虚拟环境（可选）
3. 运行 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt 命令安装程序所需模块
4. 运行 python .\main.py 或者 python main.py 命令启动 XHS-Downloader
使用 uv 安装项目依赖（推荐）
1. 运行 uv sync --no-dev 命令同步环境依赖
2. 运行 uv run main.py 命令启动 XHS-Downloader

⌨️ Docker 运行

1. 获取镜像
• 方式一：使用 Dockerfile 文件构建镜像
• 方式二：使用 docker pull joeanamier/xhs-downloader 命令拉取镜像
• 方式三：使用 docker pull ghcr.io/joeanamier/xhs-downloader 命令拉取镜像
2. 创建容器
• 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）
3. 运行容器
   • 启动容器：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 模式

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",
    }
    token = "API 模式启动时输出的鉴权令牌"
    headers = {"Authorization": f"Bearer {token}"}
    response = post(server, json=data, headers=headers, timeout=10)
    print(response.json())