🔥 小红书链接提取/作品采集工具：提取账号发布、收藏、点赞、专辑作品链接；提取搜索结果作品链接、用户链接；采集小红书作品信息；提取小红书作品下载地址；下载小红书无水印作品文件！

🔥 “小红书”、“XiaoHongShu”、“RedNote” 含义相同，本项目统称为 “小红书”

📑 项目功能

🔗 支持链接

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

• 
  

  支持单次输入多个作品链接，链接之间使用空格分隔；程序会自动提取有效链接，无需额外处理！

🪟 关于终端

⭐ 推荐使用 Windows 终端 （Windows 11 默认终端）运行程序以便获得最佳显示效果！

🥣 使用方法

如果仅需下载无水印作品文件，建议选择 程序运行 或 Docker 运行；如果有其他需求，建议选择 源码运行！

2.2 版本开始，项目功能无异常的情况下，无需额外处理 Cookie！

🖱 程序运行

⭐ Mac OS、Windows 10 及以上用户可前往 Releases 或者 Actions 下载程序压缩包，解压后打开程序文件夹，双击运行 main 即可使用。

⭐ 本项目包含自动构建可执行文件的 GitHub Actions，使用者可以随时使用 GitHub Actions 将最新源码构建为可执行文件！

⭐ 自动构建可执行文件教程请查阅本文档的 构建可执行文件指南 部分；如果需要更加详细的图文教程，请 查阅文章！

注意：Mac OS 平台可执行文件 main 可能需要从终端命令行启动；受设备限制，Mac OS 平台可执行文件尚未经过测试，无法保证可用性！

若通过此方式使用程序，文件默认下载路径为：.\_internal\Volume\Download；配置文件路径为：.\_internal\Volume\settings.json

程序更新

方案一：下载并解压文件，将旧版本的 _internal\Volume 文件夹复制到新版本的 _internal 文件夹。

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

⌨️ 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 运行项目时不支持 命令行调用模式，无法使用 读取剪贴板 与 监听剪贴板 功能，可以正常粘贴内容，其他功能如有异常请反馈！

⌨️ 源码运行

1. 安装版本号为 3.12 的 Python 解释器

2. 下载本项目最新的源码或 Releases 发布的源码至本地

3. 打开终端，切换至项目根路径

4. 运行 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt 命令安装程序所需模块

5. 运行 main.py 即可使用

🛠 命令行模式

项目支持命令行运行模式，若想要下载图文作品的部分图片，可以使用此模式设置需要下载的图片序号！

注意：未设置 --index 参数时，支持传入多个作品链接，全部链接需要使用引号包围，链接之间使用空格分隔；已设置 --index 参数时，不支持传入多个作品链接，即使传入多个作品链接，程序仅处理首个作品链接！

可以使用命令行 从浏览器读取 Cookie 并写入配置文件！

命令示例：python .\main.py --browser_cookie Chrome --update_settings

bool 类型参数支持使用 true、false、1、0、yes、no、on 或 off（不区分大小写）来设置。

🖥 服务器模式

服务器模式包含 API 模式和 MCP 模式！

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

请求参数：

代码示例：

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 模式

启动：运行命令：python .\main.py mcp

关闭：按下 Ctrl + C 关闭服务器

MCP 配置示例

Streamable HTTP

MCP URL：http://127.0.0.1:5556/mcp/

📜 其他说明

• 由于作品链接携带日期信息，使用先前日期获取的作品链接可能会被风控，建议下载作品文件时使用最新获取的作品链接

• Windows 系统需要以管理员身份运行程序才能读取 Chromium、Chrome、Edge 浏览器 Cookie

• 如果开启保存作品数据至文件功能，作品数据默认储存至 ./Volume/Download/ExploreData.db 文件

• 程序下载记录数据储存至 ./Volume/ExploreID.db 文件

• 为了避免请求频率过高对平台服务器造成影响，本项目内置请求延时机制

🕹 用户脚本

如果您的浏览器安装了 Tampermonkey 浏览器扩展程序，可以使用用户脚本体验项目功能！

用户脚本链接（右键单击复制链接）：master 分支、develop 分支

提示：使用 XHS-Downloader 用户脚本批量提取作品链接，搭配 XHS-Downloader 程序可以实现批量下载无水印作品文件！

📜 脚本说明

• 下载小红书无水印作品文件时，脚本需要花费时间处理文件，请等待片刻，请勿多次点击下载按钮

• 无水印图片文件为 PNG 格式；无水印视频文件较大，可能需要较长的时间处理，页面跳转可能会导致下载失败

• 提取账号发布、收藏、点赞、专辑作品链接时，脚本可以自动滚动页面直至加载全部作品

• 提取推荐作品链接、搜索作品、用户链接时，脚本可以自动滚动指定次数加载更多内容，默认滚动次数：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 = "作品标题 作品描述"
    user_agent = ""  # User-Agent
    cookie = ""  # 小红书网页版 Cookie，无需登录，可选参数，登录状态对数据采集有影响
    proxy = None  # 网络代理
    timeout = 5  # 请求数据超时限制，单位：秒，默认值：10
    chunk = 1024 * 1024 * 10  # 下载文件时，每次从服务器获取的数据块大小，单位：字节
    max_retry = 2  # 请求数据失败时，重试的最大次数，单位：秒，默认值：5
    record_data = False  # 是否保存作品数据至文件
    image_format = "WEBP"  # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
    folder_mode = False  # 是否将每个作品的文件储存至单独的文件夹
    image_download = True  # 图文、图集作品文件下载开关
    video_download = True  # 视频作品文件下载开关
    live_download = False  # 图文动图文件下载开关
    download_record = True  # 是否记录下载成功的作品 ID
    language = "zh_CN"  # 设置程序提示语言
    author_archive = True  # 是否将每个作者的作品存至单独的文件夹
    write_mtime = True  # 是否将作品文件的 修改时间 修改为作品的发布时间
    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,
        user_agent=user_agent,
        cookie=cookie,
        proxy=proxy,
        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,
        live_download=live_download,
        download_record=download_record,
        language=language,
        read_cookie=read_cookie,
        author_archive=author_archive,
        write_mtime=write_mtime,
    ) as xhs:  # 使用自定义参数
        download = True  # 是否下载作品文件，默认值：False
        # 返回作品详细信息，包括下载地址
        # 获取数据失败时返回空字典
        print(
            await xhs.extract(
                demo_link,
                download,
                index=[
                    1,
                    2,
                    5,
                ],
            )
        )

📋 读取剪贴板

项目使用 pyperclip 实现读取剪贴板功能，该模块在不同的系统上会有差异。

在 Windows 上，不需要额外的模块。

在 Mac 上，该模块使用 pbcopy 和 pbpaste 命令，这些命令应该随操作系统一起提供。

在 Linux 上，该模块使用 xclip 或 xsel 命令，这些命令应该随操作系统一起提供。否则，请运行 "sudo apt-get install xclip" 或 "sudo apt-get install xsel"（注意：xsel 似乎并不总是有效）

在其他 Linux 系统上，你需要安装 qtpy 或 PyQT5 模块。

⚙️ 配置文件

项目根目录下的 settings.json 文件，首次运行自动生成，可以自定义部分运行参数。

如果设置了无效的参数值，程序将会使用参数默认值！

如果 author_archive 参数设置为 true，程序会把每个作者的作品储存至单独的文件夹；当作者的昵称发生变化时，程序会自动更新已下载作品文件名称中的作者昵称部分！

除此之外，你还可以通过设置 mapping_data 参数为某个作者设置别名；如果对某个作者设置了别名，程序会使用你设置的作者别名去替代作者昵称！

其他说明：user_agent参数获取示例；强烈建议根据实际浏览器信息进行设置！

🌐 Cookie

2.2 版本开始，项目功能无异常的情况下，无需额外处理 Cookie！

1. 打开浏览器（可选无痕模式启动），访问 https://www.xiaohongshu.com/explore

2. 登录小红书账号（可跳过）

3. 按下 F12 打开开发人员工具

4. 选择 网络 选项卡

5. 勾选 保留日志

6. 在 过滤 输入框输入 cookie-name:web_session

7. 选择 Fetch/XHR 筛选器

8. 点击小红书页面任意作品

9. 在 网络 选项卡选择任意数据包（如果无数据包，重复步骤7）

10. 全选复制 Cookie 写入程序或配置文件

🗳 下载记录

XHS-Downloader 会将下载过的作品 ID 储存至数据库，当重复下载相同的作品时，XHS-Downloader 会自动跳过该作品的文件下载（即使作品文件不存在），如果想要重新下载作品文件，请先删除数据库中对应的作品 ID，再使用 XHS-Downloader 下载作品文件！

该功能默认开启，如果关闭该功能，XHS-Downloader 会检查文件是否存在，若文件存在则跳过下载！