# XHS-GREPER

**Repository Path**: codecow8848/xhs-greper

## Basic Information

- **Project Name**: XHS-GREPER
- **Description**: 用来抓取XHS帖子的程序
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-18
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<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="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>
<p>本文档仅介绍 <b>GUI 图形界面</b> 的使用方式。</p>
</div>
<hr>
<h1>📑 项目功能</h1>
<ul><b>程序功能（GUI 图形界面）</b>
<li>✅ 采集小红书作品信息</li>
<li>✅ 提取小红书作品下载地址</li>
<li>✅ 下载小红书作品文件（图文、图集、视频、livePhoto）</li>
<li>✅ 下载视频作品封面文件</li>
<li>✅ 一次粘贴多个作品链接，批量下载</li>
<li>✅ 上传 Excel 表格批量导入作品链接</li>
<li>✅ 自动跳过已下载的作品文件</li>
<li>✅ 作品文件完整性处理机制</li>
<li>✅ 自定义图文作品文件下载格式</li>
<li>✅ 自定义作品文件名称格式</li>
<li>✅ 持久化储存作品信息至文件</li>
<li>✅ 作品文件储存至单独文件夹 / 按作者归档</li>
<li>✅ 后台监听剪贴板，复制链接即自动下载</li>
<li>✅ 记录已下载作品 ID，支持下载记录管理</li>
<li>✅ 支持文件断点续传下载</li>
<li>✅ 智能识别作品文件类型</li>
<li>✅ 自动更新作者昵称</li>
<li>✅ 支持中英文界面切换</li>
</ul>
<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="">
<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>GUI 图形界面模式下，可以通过 <b>程序运行</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> 下载程序压缩包，解压后打开程序文件夹，双击运行 <code>main</code>（Windows 下为 <code>main.exe</code>）即可打开 GUI 图形界面。</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> 命令启动 GUI 图形界面</li>
</ol>
<ol><b>使用 uv 安装项目依赖（推荐）</b>
<li>运行 <code>uv sync --no-dev</code> 命令同步环境依赖</li>
<li>运行 <code>uv run main.py</code> 命令启动 GUI 图形界面</li>
</ol>
</ol>
<h1>🖥 GUI 界面与功能说明</h1>
<h2>首次启动</h2>
<p>第一次启动程序时，会弹出 <b>免责声明</b> 弹窗。请仔细阅读免责声明内容，点击 <b>已阅读并同意</b> 进入主界面；点击 <b>不同意并退出</b> 将关闭程序。</p>
<p>主界面左侧为导航栏，包含以下页面：<b>创建任务</b>、<b>任务队列</b>、<b>剪贴板模式</b>、<b>下载记录</b>、<b>运行日志</b>、<b>程序设置</b>、<b>免责声明</b>、<b>关于项目</b>。</p>
<h2>➕ 创建任务</h2>
<p>在输入框中粘贴小红书作品链接，支持一次粘贴多个链接（使用空格或换行分隔），程序会自动提取有效链接。</p>
<ul>
<li><b>图片序号：</b>仅处理单个链接时可填写，用于下载图文作品中的指定图片，例如 <code>1 3 5</code>；留空表示下载全部图片。</li>
<li><b>上传 Excel 表格：</b>点击按钮选择包含「原帖链接」列的 Excel 文件（<code>.xlsx</code>），程序会读取表格中的作品链接并自动批量导入（可通过「列名或列号」指定链接所在列，默认为 <code>原帖链接</code>）。</li>
<li><b>读取剪贴板：</b>将系统剪贴板内容读取到输入框。</li>
<li><b>读取剪贴板并处理：</b>读取剪贴板内容并直接创建下载任务。</li>
<li><b>清空输入框：</b>清空输入框内容。</li>
<li><b>处理任务：</b>将输入框中的链接加入下载任务队列。</li>
</ul>
<h2>📋 任务队列</h2>
<p>展示当前任务的下载状态，顶部显示 <b>待处理</b>、<b>成功</b>、<b>失败</b>、<b>跳过</b> 的统计数量，并提供筛选按钮。</p>
<ul>
<li><b>文件下载进度：</b>实时显示每个文件的下载进度。</li>
<li><b>重试：</b>对失败的任务点击 <b>重试</b> 可重新加入队列。</li>
<li><b>打开下载文件夹：</b>在系统文件管理器中打开当前作品下载目录。</li>
<li><b>清理已结束任务：</b>移除已结束（成功/失败/跳过/取消）的任务记录。</li>
</ul>
<h2>📎 剪贴板模式</h2>
<p>点击 <b>开启监听</b> 后，程序会在后台监听系统剪贴板；当你在浏览器复制作品链接时，程序会自动提取链接并创建下载任务，无需手动粘贴。点击 <b>关闭监听</b> 停止监听，已在队列中的任务会继续处理。</p>
<h2>🗂 下载记录</h2>
<p>记录已成功下载的作品 ID，重复处理相同作品时会自动跳过。</p>
<ul>
<li><b>搜索：</b>按作品 ID 搜索下载记录。</li>
<li><b>全选本页 / 反选本页：</b>批量选择当前页记录。</li>
<li><b>删除选中记录：</b>删除选中的下载记录（不会删除已下载的文件）。</li>
<li><b>清空全部记录：</b>清空全部下载记录。</li>
</ul>
<p>如需重新下载已记录的作品，请先删除对应记录，再重新处理作品链接。</p>
<h2>📜 运行日志</h2>
<p>实时显示程序运行过程中的日志信息，便于排查问题。</p>
<h2>⚙️ 程序设置</h2>
<p>所有参数都可以在 GUI 中直接修改，点击 <b>保存配置</b> 后立即生效，点击 <b>放弃更改</b> 撤销未保存的修改。设置分为四个分组：</p>
<ul>
<li><b>下载设置：</b>工作目录、作品文件夹、作品文件名称格式、图文/视频/动态图/视频封面下载开关、图片下载格式、视频下载偏好、作品信息保存格式。</li>
<li><b>归档与记录：</b>作品归档保存模式（每个作品单独文件夹）、作者归档保存模式、按笔记 ID 创建文件夹、保存作品描述为 TXT、作品下载记录开关、作品数据记录开关、同步文件修改时间。</li>
<li><b>网络与请求：</b>Cookie、浏览器模拟目标、网络代理、下载时使用代理、请求超时时间、重试次数、下载数据块大小。</li>
<li><b>通用设置：</b>程序语言（简体中文 / English）、脚本服务器开关。</li>
</ul>
<p>提示：如果在界面中修改配置无法正常交互，也可以直接编辑配置文件 <code>./Volume/settings.json</code>，修改后需重启程序才能生效。</p>
<h2>ℹ️ 关于项目</h2>
<p>查看程序版本、项目作者、开源协议、项目仓库等信息，并可点击 <b>检查更新</b> 检测新版本。</p>
<h1 id="cookie">🌐 获取 Cookie（可选）</h1>
<p>Cookie 为非强制项，但配置 Cookie 可以获得更高画质的视频文件（无需登录账号）。</p>
<ol>
<li>打开浏览器（可选无痕模式启动），访问 <code>https://www.xiaohongshu.com/explore</code></li>
<li>登录小红书账号（可跳过）</li>
<li>按下 <code>F12</code> 打开开发人员工具</li>
<li>选择 <code>网络</code> 选项卡</li>
<li>勾选 <code>保留日志</code></li>
<li>在 <code>过滤</code> 输入框输入 <code>cookie-name:web_session</code></li>
<li>选择 <code>Fetch/XHR</code> 筛选器</li>
<li>点击小红书页面任意作品</li>
<li>在 <code>网络</code> 选项卡选择任意数据包（如果无数据包，重复步骤7）</li>
<li>全选复制 Cookie，粘贴到 GUI「程序设置 → 网络与请求 → Cookie」输入框中并保存</li>
</ol>
<br>
<img src="static/screenshot/获取Cookie示意图.png" alt="">
<h1>🗳 下载记录说明</h1>
<p>XHS-Downloader 会将下载过的作品 ID 储存至数据库，当重复下载相同的作品时，XHS-Downloader 会自动跳过该作品的文件下载（即使作品文件不存在），如果想要重新下载作品文件，请先在「下载记录」页面删除数据库中对应的作品 ID，再重新下载！</p>
<p>该功能默认开启，如果关闭该功能（程序设置 → 归档与记录 → 作品下载记录开关），XHS-Downloader 会检查文件是否存在，若文件存在则跳过下载！</p>
<ul>
<li>如果开启保存作品数据至文件功能，作品数据默认储存至 <code>./Volume/Download/ExploreData.db</code> 文件</li>
<li>程序下载记录数据储存至 <code>./Volume/ExploreID.db</code> 文件</li>
</ul>
<h1>⚠️ 免责声明</h1>
<ol>
<li>使用者对本项目的使用由使用者自行决定，并自行承担风险。作者对使用者使用本项目所产生的任何损失、责任、或风险概不负责。</li>
<li>本项目的作者提供的代码和功能是基于现有知识和技术的开发成果。作者按现有技术水平努力确保代码的正确性和安全性，但不保证代码完全没有错误或缺陷。</li>
<li>本项目依赖的所有第三方库、插件或服务各自遵循其原始开源或商业许可，使用者需自行查阅并遵守相应协议，作者不对第三方组件的稳定性、安全性及合规性承担任何责任。</li>
<li>使用者在使用本项目时必须严格遵守 <a href="https://github.com/JoeanAmier/XHS-Downloader/blob/master/LICENSE">GNU
    General Public License v3.0</a> 的要求，并在适当的地方注明使用了 <a
        href="https://github.com/JoeanAmier/XHS-Downloader/blob/master/LICENSE">GNU General Public License
    v3.0</a> 的代码。
</li>
<li>使用者在使用本项目的代码和功能时，必须自行研究相关法律法规，并确保其使用行为合法合规。任何因违反法律法规而导致的法律责任和风险，均由使用者自行承担。</li>
<li>使用者不得使用本工具从事任何侵犯知识产权的行为，包括但不限于未经授权下载、传播受版权保护的内容，开发者不参与、不支持、不认可任何非法内容的获取或分发。</li>
<li>本项目不对使用者涉及的数据收集、存储、传输等处理活动的合规性承担责任。使用者应自行遵守相关法律法规，确保处理行为合法正当；因违规操作导致的法律责任由使用者自行承担。</li>
<li>使用者在任何情况下均不得将本项目的作者、贡献者或其他相关方与使用者的使用行为联系起来，或要求其对使用者使用本项目所产生的任何损失或损害负责。</li>
<li>本项目的作者不会提供 XHS-Downloader 项目的付费版本，也不会提供与 XHS-Downloader 项目相关的任何商业服务。</li>
<li>基于本项目进行的任何二次开发、修改或编译的程序与原创作者无关，原创作者不承担与二次开发行为或其结果相关的任何责任，使用者应自行对因二次开发可能带来的各种情况负全部责任。</li>
<li>本项目不授予使用者任何专利许可；若使用本项目导致专利纠纷或侵权，使用者自行承担全部风险和责任。未经作者或权利人书面授权，不得使用本项目进行任何商业宣传、推广或再授权。</li>
<li>作者保留随时终止向任何违反本声明的使用者提供服务的权利，并可能要求其销毁已获取的代码及衍生作品。</li>
<li>作者保留在不另行通知的情况下更新本声明的权利，使用者持续使用即视为接受修订后的条款。</li>
</ol>
<b>在使用本项目的代码和功能之前，请您认真考虑并接受以上免责声明。如果您对上述声明有任何疑问或不同意，请不要使用本项目的代码和功能。如果您使用了本项目的代码和功能，则视为您已完全理解并接受上述免责声明，并自愿承担使用本项目的一切风险和后果。</b>
<h1>✉️ 联系作者</h1>
<ul>
<li>作者邮箱：yonglelolu@foxmail.com</li>
<li>作者微信: Downloader_Tools</li>
<li>微信公众号: Downloader Tools</li>
<li><b>Discord 社区</b>: <a href="https://discord.com/invite/ZYtmgKud9Y">点击加入社区</a></li>
<li>QQ 群聊: <a href="https://github.com/JoeanAmier/XHS-Downloader/blob/master/static/QQ%E7%BE%A4%E8%81%8A%E4%BA%8C%E7%BB%B4%E7%A0%81.png">扫码加入群聊</a></li>
</ul>
<p><b>说明：</b>QQ 群聊仅限于讨论项目使用问题，严禁发布任何广告，严禁讨论任何账号交易、账号流量、流量变现、灰色产业等相关的内容！</p>
<p>✨ <b>作者的其他开源项目：</b></p>
<ul>
<li><b>DouK-Downloader（抖音、TikTok）</b>：<a href="https://github.com/JoeanAmier/TikTokDownloader">https://github.com/JoeanAmier/TikTokDownloader</a></li>
<li><b>KS-Downloader（快手、KuaiShou）</b>：<a href="https://github.com/JoeanAmier/KS-Downloader">https://github.com/JoeanAmier/KS-Downloader</a></li>
</ul>
<h1>♥️ 支持项目</h1>
<p>如果 <b>XHS-Downloader</b> 对您有帮助，请考虑为它点个 <b>Star</b> ⭐，感谢您的支持！</p>
<table>
<thead>
<tr>
<th align="center">微信(WeChat)</th>
<th align="center">支付宝(Alipay)</th>
</tr>
</thead>
<tbody><tr>
<td align="center"><img src="./static/微信赞助二维码.png" alt="微信赞助二维码" height="200" width="200"></td>
<td align="center"><img src="./static/支付宝赞助二维码.png" alt="支付宝赞助二维码" height="200" width="200"></td>
</tr>
</tbody>
</table>
<p>如果您愿意，可以考虑提供资助为 <b>XHS-Downloader</b> 提供额外的支持！</p>
<h1>⭐ Star 趋势</h1>
<a href="https://www.star-history.com/?repos=joeanamier%2Fxhs-downloader&type=timeline&releases=&legend=bottom-right">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=joeanamier/xhs-downloader&type=timeline&theme=dark&legend=bottom-right" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=joeanamier/xhs-downloader&type=timeline&legend=bottom-right" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=joeanamier/xhs-downloader&type=timeline&legend=bottom-right" />
 </picture>
</a>