从刷屏动图到永久珍藏：XHS-Downloader LivePhoto全链路处理指南

2026-02-04 04:39:37作者：裴锟轩Denise

你是否遇到过这样的困扰：小红书上刷到的精彩LivePhoto动图，想保存却只能得到静态图片？本文将带你通过XHS-Downloader这款开源工具，从获取链接到最终保存，完整掌握LivePhoto的下载与处理方法，让转瞬即逝的动态瞬间成为永久珍藏。

认识LivePhoto与XHS-Downloader

LivePhoto是一种特殊的媒体格式，它在拍摄照片的同时会录制一段短视频，让静态图片"动起来"。XHS-Downloader作为一款基于AIOHTTP模块实现的小红书图文/视频作品采集工具，不仅支持普通图片和视频的下载，还能处理LivePhoto文件。

XHS-Downloader的核心功能模块位于source/application/目录下，其中download.py负责文件下载逻辑，image.py和video.py则分别处理图片和视频文件的解析与保存。

准备工作：安装与配置

在开始下载LivePhoto之前，我们需要先完成XHS-Downloader的安装和基础配置。

安装方式选择

XHS-Downloader提供了多种安装方式，你可以根据自己的需求选择：

程序运行：适合仅需下载无水印作品文件的用户。前往项目发布页面下载对应系统的压缩包，解压后双击运行main即可。

Docker运行：适合熟悉容器技术的用户。使用以下命令拉取镜像并启动：

docker pull joeanamier/xhs-downloader
docker run --name xhs-downloader -p 5556:5556 -v xhs_downloader_volume:/app/Volume -it joeanamier/xhs-downloader

源码运行：适合开发者或需要自定义功能的用户。首先克隆仓库：

git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader

然后安装依赖：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

最后运行：

python main.py

基础配置

对于LivePhoto下载，我们需要特别关注配置文件中的live_download参数。该参数默认为false，需要将其设置为true才能开启LivePhoto下载功能。配置文件路径为./Volume/settings.json，你可以直接编辑该文件，或通过程序的设置界面进行修改。

下载LivePhoto的三种方法

XHS-Downloader提供了多种方式来下载小红书内容，包括图形界面、命令行和API调用。下面我们将详细介绍这三种方法如何应用于LivePhoto下载。

图形界面操作

启动XHS-Downloader后，你会看到主界面。
在输入框中粘贴小红书作品链接。
确保"下载LivePhoto"选项已勾选。
点击"下载"按钮开始处理。

命令行模式

对于熟悉命令行的用户，可以直接使用命令行模式下载LivePhoto：

python main.py --live_download true "https://www.xiaohongshu.com/explore/作品ID?xsec_token=XXX"

其中--live_download true参数用于开启LivePhoto下载功能。你也可以通过编辑配置文件，将live_download设置为true，这样就不需要每次都在命令行中指定该参数了。

API调用

如果需要将XHS-Downloader集成到其他应用中，可以使用API模式。首先启动API服务器：

python main.py api

然后发送POST请求到http://127.0.0.1:5556/xhs/detail，包含以下参数：

import requests

data = {
    "url": "https://www.xiaohongshu.com/explore/作品ID?xsec_token=XXX",
    "download": True,
    "live_download": True
}
response = requests.post("http://127.0.0.1:5556/xhs/detail", json=data)
print(response.json())

example.py文件中提供了更详细的API调用示例，你可以参考该文件进行二次开发。

LivePhoto文件处理流程

XHS-Downloader处理LivePhoto的流程可以分为以下几个关键步骤：

1. 链接解析

当你输入小红书作品链接后，XHS-Downloader会通过source/application/request.py模块向小红书服务器发送请求，获取作品的元数据。这个过程中会判断作品是否包含LivePhoto内容。

2. 资源下载

如果检测到LivePhoto，download.py模块会开始下载相关文件。需要注意的是，小红书的LivePhoto文件是含水印的，这是由于平台的限制。

3. 文件保存

下载完成后，文件会按照配置的路径和命名规则保存。默认情况下，文件会保存在./Volume/Download目录下。你可以通过修改配置文件中的work_path和folder_name参数来自定义保存路径，通过name_format参数自定义文件名格式。

高级技巧：批量下载与自动化

对于需要下载大量LivePhoto的用户，XHS-Downloader提供了批量下载和自动化功能。

批量下载

你可以一次输入多个作品链接，链接之间使用空格分隔。例如：

python main.py --live_download true "链接1" "链接2" "链接3"

监听剪贴板

XHS-Downloader还支持监听剪贴板功能，当检测到小红书链接时自动开始下载。这个功能可以通过source/expansion/browser.py模块实现，你需要在设置中开启"监听剪贴板"选项。

二次开发

如果你是开发者，可以基于XHS-Downloader进行二次开发，实现更复杂的自动化逻辑。example.py提供了详细的代码示例，展示如何通过代码调用XHS-Downloader的核心功能。

下面是一个简单的示例，展示如何使用Python代码批量下载LivePhoto：

from asyncio import run
from source import XHS

async def batch_download():
    links = [
        "https://www.xiaohongshu.com/explore/作品ID1?xsec_token=XXX",
        "https://www.xiaohongshu.com/explore/作品ID2?xsec_token=XXX",
        # 更多链接...
    ]
    
    async with XHS(live_download=True) as xhs:
        for link in links:
            print(f"正在下载: {link}")
            await xhs.extract(link, download=True)

run(batch_download())

常见问题与解决方案

LivePhoto下载后无法播放

如果你下载的LivePhoto文件无法播放，可能是由于以下原因：

文件不完整：网络问题可能导致文件下载不完整。XHS-Downloader有文件完整性处理机制，你可以在source/expansion/error.py中查看相关实现。如果怀疑文件不完整，可以尝试重新下载。
播放器不支持：LivePhoto是一种特殊格式，并非所有播放器都支持。建议使用最新版本的QuickTime Player或其他支持HEIF/HEVC格式的播放器。