XHS-Downloader：免费开源！小红书无水印作品采集工具全解析
项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader 🌟 为什么选择XHS-Downloader？
你是否还在为小红书作品下载受水印困扰？是否需要高效采集无水印图文/视频内容？XHS-Downloader作为一款免费开源的小红书作品采集工具，基于AIOHTTP模块构建，完美解决这些痛点。本文将从功能解析、安装指南到高级应用，全方位带你掌握这款工具的使用技巧。
读完本文你将获得：
- 无水印下载小红书图文/视频的完整方案
- 三种运行模式（GUI/TUI/命令行）的配置方法
- 批量下载与自动化采集的进阶技巧
- 二次开发与API集成的实战指南
🚀 核心功能一览
作品处理能力
XHS-Downloader提供全方位的作品采集解决方案：
- ✅ 多类型内容支持：图文、视频、LivePhoto（含水印）全格式覆盖
- ✅ 智能去重机制：自动跳过已下载作品，支持断点续传
- ✅ 自定义格式：支持PNG/WEBP/JPEG/HEIC等多种图片格式转换
- ✅ 文件管理：作品按作者/专辑自动分类，支持自定义命名规则
特色功能解析
剪贴板监听模式 后台自动监控系统剪贴板，识别小红书链接并自动下载，实现"复制即下载"的无缝体验。
MCP服务器模式 通过HTTP接口提供远程调用能力，支持：
- 批量获取作品元数据
- 指定图片序号下载
- 下载状态实时监控
- 结果JSON格式化输出
浏览器Cookie集成 自动读取Chrome/Edge等浏览器Cookie，无需手动配置，提升请求成功率：
📦 安装与部署指南
环境要求
- Python 3.12+
- 依赖库：aiohttp、pyperclip、rich等（完整列表见requirements.txt）
- 系统支持：Windows 10+、macOS 12+、Linux（Ubuntu 20.04+）
三种安装方式
1. 源码安装（推荐开发者）
# 克隆仓库
git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader
cd XHS-Downloader
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# 安装依赖
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
# 启动程序
python main.py
2. 可执行文件（推荐普通用户）
前往项目Releases页面下载对应系统的压缩包，解压后直接运行：
- Windows：双击
main.exe - macOS：终端执行
./main - Linux：终端执行
./main
默认下载路径：
./_internal/Volume/Download
配置文件路径：./_internal/Volume/settings.json
3. Docker部署（推荐服务器环境）
# 拉取镜像
docker pull joeanamier/xhs-downloader
# 启动容器（TUI模式）
docker run -p 5556:5556 -v xhs_volume:/app/Volume -it joeanamier/xhs-downloader
# 启动容器（API模式）
docker run -p 5556:5556 -v xhs_volume:/app/Volume -it joeanamier/xhs-downloader python main.py api
💻 基础使用教程
TUI图形界面
启动程序后进入交互式界面，通过方向键和回车键操作：
┌──────────────────────────────────────┐
│ XHS-Downloader │
│ │
│ 1. 输入作品链接 │
│ 2. 剪贴板监听模式 │
│ 3. 批量下载管理 │
│ 4. 设置 │
│ │
│ 版本: 2.2.0 │
└──────────────────────────────────────┘
命令行快速下载
# 单链接下载
python main.py "https://xhslink.com/xxxx"
# 批量下载（链接用空格分隔）
python main.py "url1" "url2" "url3"
# 指定图片序号下载（仅对图文作品有效）
python main.py --index 1,3,5 "https://xhslink.com/xxxx"
# 从浏览器读取Cookie
python main.py --browser_cookie Chrome --update_settings
用户脚本辅助（浏览器扩展）
- 安装Tampermonkey扩展
- 添加脚本：XHS-Downloader.js
- 小红书页面自动添加下载按钮：
- 单作品页：显示"下载无水印"按钮
- 列表页：批量选择作品下载
- 个人主页：提取全部作品链接
⚙️ 高级配置指南
自定义下载参数
修改settings.json配置文件实现个性化需求：
{
"name_format": "发布时间 作者昵称 作品标题",
"image_format": "PNG",
"author_archive": true,
"folder_mode": false,
"download_record": true
}
关键参数说明：
| 参数名 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| work_path | str | 下载根路径 | ./Volume |
| name_format | str | 文件名格式模板 | 发布时间 作者昵称 作品标题 |
| image_format | str | 图片格式 | PNG |
| author_archive | bool | 按作者归档 | false |
| folder_mode | bool | 作品单独文件夹 | false |
| proxy | str | 网络代理 | null |
API接口开发
启动API服务：
python main.py api
访问http://127.0.0.1:5556/docs查看自动生成的Swagger文档，核心接口示例：
请求作品详情
import requests
def get_xhs_detail(url):
api_url = "http://127.0.0.1:5556/xhs/detail"
payload = {
"url": url,
"download": True,
"index": [1,3,5] # 指定下载第1/3/5张图片
}
response = requests.post(api_url, json=payload)
return response.json()
# 使用示例
result = get_xhs_detail("https://xhslink.com/xxxx")
print(result["title"], result["download_urls"])
🛠️ 实战案例
案例1：批量下载收藏夹作品
-
使用用户脚本提取收藏夹所有链接：
- 访问小红书收藏页面
- 点击脚本"提取收藏链接"按钮
- 导出为
favorites.txt（一行一个链接）
-
执行批量下载命令：
# Windows
for /f "tokens=*" %i in (favorites.txt) do python main.py "%i"
# Linux/macOS
cat favorites.txt | xargs -I {} python main.py "{}"
案例2：配合Python实现定时采集
from datetime import datetime
from time import sleep
import subprocess
def scheduled_download(interval=3600):
"""每小时检查一次目标账号最新作品"""
target_url = "https://www.xiaohongshu.com/user/profile/xxx"
while True:
print(f"[{datetime.now()}] 检查更新...")
# 调用用户脚本提取最新作品链接
links = subprocess.check_output(
["python", "extract_links.py", target_url]
).decode().splitlines()
for link in links:
subprocess.run(["python", "main.py", link])
sleep(interval)
if __name__ == "__main__":
scheduled_download()
🔧 常见问题解决
Cookie相关问题
Q: 提示"请求失败"或"需要登录"怎么办？
A: 按以下步骤获取Cookie：
- 浏览器访问小红书官网
- F12打开开发者工具 → Network标签
- 筛选"cookie-name:web_session"
- 复制完整Cookie值到配置文件
下载速度慢解决方案
- 调整分块大小：
"chunk": 20971520（20MB） - 关闭代理：
"proxy": null - 减少重试次数：
"max_retry": 3 - 使用断点续传：确保
"download_record": true
格式转换问题
Q: 下载的HEIC格式无法打开？
A: 修改配置文件："image_format": "JPEG"，或使用扩展功能批量转换：
python -m source.expansion.converter --dir ./Download --format jpg
📝 二次开发指南
核心类结构
扩展开发示例
from source.application.download import Downloader
class CustomDownloader(Downloader):
"""自定义下载器，添加进度条显示"""
async def download(self, url, file_path):
self.show_progress = True
return await super().download(url, file_path)
def on_progress(self, downloaded, total):
"""重写进度回调"""
percent = (downloaded / total) * 100
print(f"下载进度: {percent:.2f}%", end="\r")
📄 许可证与免责声明
本项目基于GPLv3许可证开源，使用时需遵守：
- 仅用于个人学习研究
- 不得用于商业用途
- 尊重原作者知识产权
- 遵守小红书用户协议
⚠️ 注意：过度频繁的请求可能导致IP被限制，建议设置合理的请求间隔（默认已内置限流机制）。对于因违规使用导致的账号问题，项目开发者不承担任何责任。
🔄 版本更新日志
2.2.0主要更新
- ✨ 新增MCP服务器模式
- 🐛 修复合辑作品链接提取问题
- ⚡ 优化AIOHTTP连接池管理
- 🔧 完善断点续传功能
用户脚本v2.1.15
- 新增链接提取/图片下载选择模式开关
- 修复专辑作品链接提取失败问题
🌟 结语与致谢
XHS-Downloader作为开源项目，离不开社区贡献者的支持。特别感谢以下项目提供的灵感与技术支持：
- aiohttp - 异步HTTP客户端
- FastAPI - API服务框架
- Textual - TUI界面库
- pyperclip - 剪贴板操作
如果本工具对你有帮助，欢迎通过以下方式支持项目发展：
- 项目仓库点星 ⭐
- 提交Issue反馈问题
- 贡献代码完善功能
- 分享给有需要的朋友
让我们共同维护一个高效、安全、合规的内容采集工具生态！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
