XHS-Downloader

<div align="center"> <img src="static/XHS-Downloader.png" alt="XHS-Downloader" height="256" width="256"><br> <h1>XHS-Downloader</h1> <p>简体中文 | <a href="README_EN.md">English</a></p> <a href="https://www.star-history.com/joeanamier/xhs-downloader"> <picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=JoeanAmier/XHS-Downloader&type=rank&theme=dark" /><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=JoeanAmier/XHS-Downloader&type=rank" /><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=JoeanAmier/XHS-Downloader&type=rank" /></picture> <picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=JoeanAmier/XHS-Downloader&type=trending&theme=dark" /><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=JoeanAmier/XHS-Downloader&type=trending" /><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=JoeanAmier/XHS-Downloader&type=trending" /></picture> </a> <br> <img alt="GitHub" src="https://img.shields.io/github/license/JoeanAmier/XHS-Downloader?style=flat-square"> <img alt="GitHub forks" src="https://img.shields.io/github/forks/JoeanAmier/XHS-Downloader?style=flat-square&color=55efc4"> <img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/JoeanAmier/XHS-Downloader?style=flat-square&color=fda7df"> <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/JoeanAmier/XHS-Downloader?style=flat-square&color=a29bfe"> <img alt="GitHub release (with filter)" src="https://img.shields.io/github/v/release/JoeanAmier/XHS-Downloader?style=flat-square&color=48dbfb"> <br> <img alt="Static Badge" src="https://img.shields.io/badge/Python-≥3.12-b8e994?style=flat-square&logo=python&labelColor=3dc1d3"> <img alt="Static Badge" src="https://img.shields.io/badge/UserScript-ffec3d?style=flat-square&logo=tampermonkey&logoColor=%2300485B"> <img src="https://img.shields.io/badge/Sourcery-enabled-884898?style=flat-square&color=1890ff" alt=""> <img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/joeanamier/xhs-downloader?style=flat-square&color=badc58"> <img alt="GitHub all releases" src="https://img.shields.io/github/downloads/JoeanAmier/XHS-Downloader/total?style=flat-square&color=ffdd59"> <br> <p>🔥 <b>小红书（XiaoHongShu、RedNote）链接提取/作品采集工具！</b></p> </div> <hr> <h1>📑 项目功能</h1> <details> <summary>项目程序与用户脚本功能清单，快速了解项目能力（点击展开）</summary> <ul><b>程序功能</b> <li>✅ 采集小红书作品信息</li> <li>✅ 提取小红书作品下载地址</li> <li>✅ 下载小红书作品文件</li> <li>✅ 下载视频作品封面文件</li> <li>✅ 下载小红书 livePhoto 文件</li> <li>✅ 自动跳过已下载的作品文件</li> <li>✅ 作品文件完整性处理机制</li> <li>✅ 自定义图文作品文件下载格式</li> <li>✅ 持久化储存作品信息至文件</li> <li>✅ 作品文件储存至单独文件夹</li> <li>✅ 后台监听剪贴板下载作品</li> <li>✅ 记录已下载作品 ID</li> <li>✅ 支持命令行下载作品文件</li> <li>☑️ 从浏览器读取 Cookie</li> <li>✅ 自定义文件名称格式</li> <li>✅ 支持 API 调用功能</li> <li>✅ 支持 MCP 调用功能</li> <li>✅ 支持文件断点续传下载</li> <li>✅ 智能识别作品文件类型</li> <li>✅ 支持设置作者备注</li> <li>✅ 自动更新作者昵称</li> </ul> <ul><a href="#user-scripts"><b>脚本功能</b></a> <li>✅ 下载小红书作品文件</li> <li>✅ 提取推荐页面作品链接</li> <li>✅ 提取账号发布作品链接</li> <li>✅ 提取账号收藏作品链接</li> <li>✅ 提取账号点赞作品链接</li> <li>✅ 提取账号专辑作品链接</li> <li>✅ 提取搜索结果作品链接</li> <li>✅ 提取搜索结果用户链接</li> </ul> </details> <h1>📸 程序截图</h1> <p><a href="https://www.bilibili.com/video/BV1Rv8z62Ebx/">前往 bilibili 观看演示</a>；<a href="https://youtu.be/1WBKuLlOeNw">前往 YouTube 观看演示</a></p> <p><b>GUI 界面截图</b></p> <img src="static/screenshot/程序运行截图CN1.png" alt=""> <hr> <p><b>TUI 界面截图</b>（模式命令：<code>python .\main.py TUI</code>）</p> <img src="static/screenshot/程序运行截图CN2.png" alt=""> <h1>🔗 支持链接</h1> <ul> <li><code>https://www.xiaohongshu.com/explore/作品ID?xsec_token=XXX</code></li> <li><code>https://www.xiaohongshu.com/discovery/item/作品ID?xsec_token=XXX</code></li> <li><code>https://www.xiaohongshu.com/user/profile/作者ID/作品ID?xsec_token=XXX</code></li> <li><code>https://xhslink.com/分享码</code></li> <br/> <p><b>支持单次输入多个作品链接，链接之间使用空格分隔；程序会自动提取有效链接，无需额外处理！</b></p> </ul> <h1>🥣 使用方法</h1> <p>如果仅需下载作品文件，建议选择 <b>程序运行</b> 或 <b>Docker 运行</b>；如果有其他需求，建议选择 <b>源码运行</b>！</p> <p>⚠️ Cookie 配置为非强制项；如遇功能异常，建议配置或更新 Cookie 后再次尝试！</p> <p>⚠️ 未设置 Cookie 时，视频作品只能下载低分辨率文件；建议配置 Cookie 以获取更高画质（无需登录账号）！</p> <h2>🖱 程序运行</h2> <p>⭐ Mac OS、Windows 10 及以上用户可前往 <a href="https://github.com/JoeanAmier/XHS-Downloader/releases/latest">Releases</a> 或者 <a href="https://github.com/JoeanAmier/XHS-Downloader/actions">Actions</a> 下载程序压缩包，解压后打开程序文件夹，双击运行 <code>main</code> 即可使用。</p> <p>⭐ 本项目包含自动构建可执行文件的 GitHub Actions，使用者可以随时使用 GitHub Actions 将最新源码构建为可执行文件！</p> <p>⭐ 自动构建可执行文件教程请查阅本文档的 <code>构建可执行文件指南</code> 部分；如果需要更加详细的图文教程，请 <a href="https://mp.weixin.qq.com/s/TorfoZKkf4-x8IBNLImNuw">查阅文章</a>！</p> <p><strong>注意：由于 Mac OS 平台的可执行文件 <code>main</code> 未经过代码签名，首次运行时会受到系统安全限制。请先在终端执行 <code>xattr -cr 项目文件夹路径</code> 命令移除安全标记，执行一次后即可正常运行。</strong></p> <p>若通过此方式使用程序，文件默认下载路径为：<code>.\Volume\Download</code>；配置文件路径为：<code>.\Volume\settings.json</code></p> <h3>程序更新</h3> <p><strong>方案一：</strong>下载并解压文件，将旧版本的 <code>Volume</code> 文件夹复制到新版本的程序根目录。</p> <p><strong>方案二：</strong>下载并解压文件（不要运行程序），复制全部文件，直接覆盖旧版本文件。</p> <h2>⌨️ 源码运行</h2> <ol> <li>安装不低于 <code>3.12</code> 版本的 <a href="https://www.python.org/">Python</a> 解释器</li> <li>下载最新的源码或 <a href="https://github.com/JoeanAmier/XHS-Downloader/releases/latest">Releases</a> 发布的源码至本地</li> <ol><b>使用 pip 安装项目依赖</b> <li>运行 <code>python -m venv venv</code> 命令创建虚拟环境（可选）</li> <li>运行 <code>.\venv\Scripts\activate.ps1</code> 或者 <code>venv\Scripts\activate</code> 命令激活虚拟环境（可选）</li> <li>运行 <code>pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt</code> 命令安装程序所需模块</li> <li>运行 <code>python .\main.py</code> 或者 <code>python main.py</code> 命令启动 XHS-Downloader</li> </ol> <ol><b>使用 uv 安装项目依赖（推荐）</b> <li>运行 <code>uv sync --no-dev</code> 命令同步环境依赖</li> <li>运行 <code>uv run main.py</code> 命令启动 XHS-Downloader</li> </ol> </ol> <h2>⌨️ Docker 运行</h2> <ol> <li>获取镜像</li> <ul> <li>方式一：使用 <code>Dockerfile</code> 文件构建镜像</li> <li>方式二：使用 <code>docker pull joeanamier/xhs-downloader</code> 命令拉取镜像</li> <li>方式三：使用 <code>docker pull ghcr.io/joeanamier/xhs-downloader</code> 命令拉取镜像</li> </ul> <li>创建容器</li> <ul> <li>TUI 模式：<code>docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it &lt;镜像名称&gt;</code></li> <li>API 模式：<code>docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it &lt;镜像名称&gt; python main.py api</code></li> <li>MCP 模式：<code>docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it &lt;镜像名称&gt; python main.py mcp</code></li> <br><b>注意：</b>此处的 <code>&lt;镜像名称&gt;</code> 需与您在第一步中使用的镜像名称保持一致（<code>joeanamier/xhs-downloader</code> 或 <code>ghcr.io/joeanamier/xhs-downloader</code>） </ul> <li>运行容器 <ul> <li>启动容器：<code>docker start -i 容器名称/容器 ID</code></li> <li>重启容器：<code>docker restart -i 容器名称/容器 ID</code></li> </ul> </li> </ol> <p>Docker 运行项目时不支持 <b>命令行调用模式</b>，无法使用 <b>读取剪贴板</b> 与 <b>监听剪贴板</b> 功能，可以正常粘贴内容，其他功能如有异常请反馈！</p> <h1>🛠 命令行模式</h1> <details> <summary>命令行模式说明，适合习惯命令行操作或需要脚本化调用的用户（点击展开）</summary> <p>项目支持命令行运行模式，可通过命令行参数直接下载作品文件，也可以设置需要下载的图片序号！</p> <p><strong>注意：</strong>未设置 <code>--index</code> 参数时，支持传入多个作品链接，全部链接需要使用引号包围，链接之间使用空格分隔；已设置 <code>--index</code> 参数时，不支持传入多个作品链接，即使传入多个作品链接，程序仅处理首个作品链接！</p> <p><code>bool</code> 类型参数支持使用 <code>true</code>、<code>false</code>、<code>1</code>、<code>0</code>、<code>yes</code>、<code>no</code>、<code>on</code> 或 <code>off</code>（不区分大小写）来设置。</p> <h2>从浏览器读取 Cookie</h2> <p>该功能已失效，请参考 <a href="#cookie">获取 Cookie</a> 教程！</p> <p><del>可以使用命令行实现 <b>从浏览器读取 Cookie 并写入配置文件！</b></del></p> <p><del>命令示例：<code>python .\main.py --browser_cookie Chrome --update_settings</code></del></p> <p><del>兼容性提醒：此功能依赖的第三方模块已长期未更新，可能无法正常支持最新浏览器版本。若功能出现异常，请尝试手动获取 Cookie！</del></p> <hr> <img src="static/screenshot/命令行模式截图CN1.png" alt=""> <hr> <img src="static/screenshot/命令行模式截图CN2.png" alt=""> </details> <h1>🖥 服务器模式</h1> <p>服务器模式包含 API 模式和 MCP 模式！</p> <h2>API 模式</h2> <details> <summary>API 模式说明，适合需要调用接口获取作品数据或下载文件的开发者（点击展开）</summary> <p><b>启动：</b>运行命令：<code>python .\main.py api</code></p> <p><b>关闭：</b>按下 <code>Ctrl</code> + <code>C</code> 关闭服务器</p> <p>访问 <code>http://127.0.0.1:5556/docs</code> 或者 <code>http://127.0.0.1:5556/redoc</code>；你会看到自动生成的交互式 API 文档！</p> <p><b>请求接口：</b><code>/xhs/detail</code></p> <p><b>请求方法：</b><code>POST</code></p> <p><b>请求格式：</b><code>JSON</code></p> <p><b>请求参数：</b></p> <table> <thead> <tr> <th align="center">参数</th> <th align="center">类型</th> <th align="center">含义</th> <th align="center">默认值</th> </tr> </thead> <tbody> <tr> <td align="center">url</td> <td align="center">str</td> <td align="center">小红书作品链接，自动提取，不支持多链接；必需参数</td> <td align="center">无</td> </tr> <tr> <td align="center">download</td> <td align="center">bool</td> <td align="center">是否下载作品文件；设置为 <code>true</code> 将会耗费更多时间；可选参数</td> <td align="center">false</td> </tr> <tr> <td align="center">index</td> <td align="center">list[int]</td> <td align="center">下载指定序号的图片文件，仅对图文作品生效；<code>download</code> 参数设置为 <code>false</code> 时不生效；可选参数</td> <td align="center">null</td> </tr> <tr> <td align="center">cookie</td> <td align="center">str</td> <td align="center">请求数据时使用的 Cookie；可选参数</td> <td align="center">配置文件 cookie 参数</td> </tr> <tr> <td align="center">proxy</td> <td align="center">str</td> <td align="center">请求数据时使用的代理；可选参数</td> <td align="center">配置文件 proxy 参数</td> </tr> <tr> <td align="center">check_record</td> <td align="center">bool</td> <td align="center">是否跳过已有下载记录的作品；可选参数</td> <td align="center">true</td> </tr> </tbody> </table> <p><b>代码示例：</b></p> <pre> 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()) </pre> </details> <h2>MCP 模式</h2> <details> <summary>MCP 模式说明，适合需要启动 MCP 服务接入 AI 助手等工具的开发者（点击展开）</summary> <p><b>启动：</b>运行命令：<code>python .\main.py mcp</code></p> <p><b>关闭：</b>按下 <code>Ctrl</code> + <code>C</code> 关闭服务器</p> <h3>MCP 配置示例</h3> <h4>Streamable HTTP</h4> <p><b>MCP URL：</b><code>http://127.0.0.1:5556/mcp/</code></p> <img src="static/screenshot/MCP配置示例.png" alt="MCP配置示例"> <h3>MCP 调用示例</h3> <h4><strong>获取小红书作品信息</strong></h4> <img src="static/screenshot/MCP获取数据.png" alt="MCP获取数据"> <hr> <h4><strong>下载小红书作品文件</strong></h4> <p>下载图文作品时可以指定需要下载的图片序号；默认不返回作品信息，如需返回作品信息，请在对话时明确表述。</p> <img src="static/screenshot/MCP下载文件1.png" alt="MCP下载文件"> <hr> <img src="static/screenshot/MCP下载文件2.png" alt="MCP下载文件"> </details> <h1>📜 其他说明</h1> <ul> <li>由于作品链接携带日期信息，使用先前日期获取的作品链接可能会被风控，建议下载作品文件时使用最新获取的作品链接</li> <li>如果需要程序使用代理请求数据，请在配置文件 <code>settings.json</code> 设置 <code>proxy</code> 参数</li> <li><del>Windows 系统需要以管理员身份运行程序才能读取 Chromium、Chrome、Edge 浏览器 Cookie</del></li> <li>如果开启保存作品数据至文件功能，作品数据默认储存至 <code>./Volume/Download/ExploreData.db</code> 文件</li> <li>程序下载记录数据储存至 <code>./Volume/ExploreID.db</code> 文件</li> <li>为了避免请求频率过高对平台服务器造成影响，本项目内置请求延时机制</li> </ul> <h1 id="user-scripts">🕹 用户脚本</h1> <p>如果您的浏览器安装了 <a href="https://www.tampermonkey.net/">Tampermonkey</a> 浏览器扩展程序，可以使用用户脚本体验项目功能！</p> <p>用户脚本链接（右键单击复制链接）：<a href="https://raw.githubusercontent.com/JoeanAmier/XHS-Downloader/refs/heads/master/static/XHS-Downloader.js">master 分支</a>、<a href="https://raw.githubusercontent.com/JoeanAmier/XHS-Downloader/refs/heads/develop/static/XHS-Downloader.js">develop 分支</a></p> <img src="static/screenshot/脚本安装教程.png" alt=""> <hr> <details> <summary>查看 Tampermonkey 用户脚本截图（点击展开）</summary> <img src="static/screenshot/用户脚本截图1.png" alt=""> <hr> <img src="static/screenshot/用户脚本截图2.png" alt=""> <hr> <img src="static/screenshot/用户脚本截图3.png" alt=""> <hr> <img src="static/screenshot/用户脚本截图4.png" alt=""> </details> <p>提示：使用 XHS-Downloader 用户脚本批量提取作品链接，搭配 XHS-Downloader 程序可以实现批量下载作品文件！</p> <p><b>修改用户脚本语言</b></p> <img src="static/screenshot/脚本切换语