JoeanAmier/XHS-Downloader

程序功能
• ✅ 采集小红书作品信息
• ✅ 提取小红书作品下载地址
• ✅ 下载小红书作品文件
• ✅ 下载视频作品封面文件
• ✅ 下载小红书 livePhoto 文件
• ✅ 自动跳过已下载的作品文件
• ✅ 作品文件完整性处理机制
• ✅ 自定义图文作品文件下载格式
• ✅ 持久化储存作品信息至文件
• ✅ 作品文件储存至单独文件夹
• ✅ 后台监听剪贴板下载作品
• ✅ 记录已下载作品 ID
• ✅ 支持命令行下载作品文件
• ☑️ 从浏览器读取 Cookie
• ✅ 自定义文件名称格式
• ✅ 支持 API 调用功能
• ✅ 支持 MCP 调用功能
• ✅ 支持文件断点续传下载
• ✅ 智能识别作品文件类型
• ✅ 支持设置作者备注
• ✅ 自动更新作者昵称

脚本功能
• ✅ 下载小红书作品文件
• ✅ 提取推荐页面作品链接
• ✅ 提取账号发布作品链接
• ✅ 提取账号收藏作品链接
• ✅ 提取账号点赞作品链接
• ✅ 提取账号专辑作品链接
• ✅ 提取搜索结果作品链接
• ✅ 提取搜索结果用户链接

项目支持命令行运行模式，可通过命令行参数直接下载作品文件，也可以设置需要下载的图片序号！

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

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

该功能已失效，请参考 获取 Cookie 教程！

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

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

兼容性提醒：此功能依赖的第三方模块已长期未更新，可能无法正常支持最新浏览器版本。若功能出现异常，请尝试手动获取 Cookie！

启动：运行命令：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())

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

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

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

下载图文作品时可以指定需要下载的图片序号；默认不返回作品信息，如需返回作品信息，请在对话时明确表述。

如果有其他需求，可以根据 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,
                ],
            )
        )

项目使用 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 文件，建议使用 在线工具 编辑配置文件内容，修改后需要重启软件才能生效。

本指南将引导您通过 Fork 本仓库并执行 GitHub Actions 自动完成基于最新源码的程序构建和打包！

1. 点击项目仓库右上角的 Fork 按钮，将本仓库 Fork 到您的个人 GitHub 账户中
2. 您的 Fork 仓库地址将类似于：https://github.com/your-username/this-repo

1. 前往您 Fork 的仓库页面
2. 点击顶部的 Settings 选项卡
3. 点击右侧的 Actions 选项卡
4. 点击 General 选项
5. 在 Actions permissions 下，选择 Allow all actions and reusable workflows 选项，点击 Save 按钮

1. 在您 Fork 的仓库中，点击顶部的 Actions 选项卡
2. 找到名为 构建可执行文件 的工作流
3. 点击右侧的 Run workflow 按钮：
   • 选择 master 或者 develop 分支
   • 点击 Run workflow

1. 在 Actions 页面中，您可以看到触发的工作流运行记录
2. 点击运行记录，查看详细的日志以了解打包进度和状态

1. 打包完成后，进入对应的运行记录页面
2. 在页面底部的 Artifacts 部分，您将看到打包的结果文件
3. 点击下载并保存到本地，即可获得打包好的程序

1. 资源使用：

   • Actions 的运行环境由 GitHub 免费提供，普通用户每月有一定的免费使用额度（2000 分钟）

2. 代码修改：

   • 您可以自由修改 Fork 仓库中的代码以定制程序打包流程
   • 修改后重新触发打包流程，您将得到自定义的构建版本

3. 与主仓库保持同步：

   • 如果主仓库更新了代码或工作流，建议您定期同步 Fork 仓库以获取最新功能和修复

A: 请确认您已按照步骤 启用 Actions，否则 GitHub 会禁止运行工作流

A:

• 检查运行日志，了解失败原因
• 确保代码没有语法错误或依赖问题
• 如果问题仍未解决，可以在本仓库的 Issues 页面 提出问题

A: 由于权限限制，您无法直接触发主仓库的 Actions。请通过 Fork 仓库的方式执行打包流程

欢迎对本项目做出贡献！为了保持代码库的整洁、高效和易于维护，请仔细阅读以下指南，以确保您的贡献能够顺利被接受和整合。

• 在开始开发前，请从 develop 分支拉取最新的代码，以此为基础进行修改；这有助于避免合并冲突并保证您的改动基于最新的项目状态。
• 如果您的更改涉及多个不相关的功能或问题，请将它们分成多个独立的提交或拉取请求。
• 每个拉取请求应尽可能专注于单一功能或修复，以便于代码审查和测试。
• 遵循现有的代码风格；请确保您的代码与项目中已有的代码风格保持一致；建议使用 Ruff 工具保持代码格式规范。
• 编写可读性强的代码；添加适当的注释帮助他人理解您的意图。
• 每个提交都应该包含一个清晰、简洁的提交信息，以描述所做的更改。提交信息应遵循以下格式：<类型>: <简短描述>
• 当您准备提交拉取请求时，请优先将它们提交到 develop 分支；这是为了给维护者一个缓冲区，在最终合并到 master 分支之前进行额外的测试和审查。
• 建议在开发前或遇到疑问时与作者沟通，确保开发方向一致，避免重复劳动或无效提交。

参考资料：

• 贡献者公约
• 如何为开源做贡献