XHS-Downloader配置文件全解析：自定义下载路径与格式设置
项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader 引言：为什么需要自定义配置？
你是否遇到过下载的小红书内容杂乱无章地堆放在默认文件夹？是否希望根据发布时间、作者或标题自动分类文件？XHS-Downloader的配置系统为你提供了灵活的个性化选项，让下载内容井然有序。本文将深入解析配置文件的核心参数，帮助你掌握路径定制、命名规则和格式转换的全部技巧。
读完本文后，你将能够：
- 自定义下载文件的存储路径和文件夹结构
- 设计符合个人习惯的文件命名规则
- 配置图片/视频的下载格式和质量
- 优化网络请求参数提升下载效率
- 迁移和备份配置文件
配置文件基础
配置文件位置与格式
XHS-Downloader使用JSON格式的配置文件(settings.json)存储所有用户偏好设置，其默认位置遵循不同操作系统的规范：
| 操作系统 | 典型路径 |
|---|---|
| Windows | C:\Users\<用户名>\AppData\Roaming\XHS-Downloader\settings.json |
| macOS | ~/Library/Application Support/XHS-Downloader/settings.json |
| Linux | ~/.config/XHS-Downloader/settings.json |
配置文件采用UTF-8编码，结构清晰，包含多个顶级配置项：
{
"work_path": "",
"folder_name": "Download",
"name_format": "发布时间 作者昵称 作品标题",
"image_format": "PNG",
"video_download": true,
// 更多配置项...
}
配置文件加载流程
核心配置详解
下载路径配置
work_path - 工作目录设置
该参数指定下载文件的根目录，留空时使用应用程序默认路径。你可以设置绝对路径来自定义位置：
{
"work_path": "/Volumes/ExternalDrive/XHS-Downloads" // macOS示例
}
{
"work_path": "D:\\小红书下载" // Windows示例(注意双反斜杠)
}
提示：路径中包含中文或空格时无需额外转义，配置系统会自动处理
folder_name - 文件夹命名
用于设置每个作品的父文件夹名称，支持固定字符串或动态变量：
{
"folder_name": "小红书收集" // 固定文件夹名称
}
或使用特殊变量创建动态结构：
{
"folder_name": "{作者昵称}/{发布年份}-{发布月份}" // 按作者和年月分类
}
支持的文件夹变量：
| 变量名 | 说明 | 示例值 |
|---|---|---|
{作者ID} | 作品作者的唯一标识 | 5d8f7e6a5b4c3d2e1f0a9b8c |
{作者昵称} | 作者公开显示名称 | 旅行摄影师小李 |
{发布年份} | 作品发布的年份 | 2025 |
{发布月份} | 作品发布的月份 | 06 |
{作品类型} | 内容类型分类 | 图文 或 视频 |
文件命名规则
name_format - 文件名模板
该参数控制下载文件的命名格式，支持多种元数据变量组合：
{
"name_format": "发布时间 作者昵称 作品标题"
}
系统会将模板中的文字替换为实际作品信息，例如生成：20250618 旅行摄影师小李 夏日海边度假攻略.jpg
支持的文件名变量：
| 变量名 | 说明 | 示例 |
|---|---|---|
发布时间 | 作品发布的时间戳 | 202506181530 |
作者昵称 | 内容创作者的名称 | 美食家小王 |
作品标题 | 作品的原始标题 | 上海必吃的10家老字号 |
作品ID | 小红书平台的作品唯一标识 | xhs123456789abcdef |
序号 | 多图作品中的图片序号 | 01, 02 |
注意：系统会自动过滤文件名中的非法字符(如
/\:*?"<>|)，确保文件系统兼容性
高级命名示例
按作品类型区分命名：
{
"name_format": "[{作品类型}] {发布时间} {标题}"
}
添加来源标识：
{
"name_format": "XHS_{作品ID}_{序号}"
}
媒体格式配置
image_format - 图片格式设置
控制下载图片的目标格式，支持多种常见图片格式：
{
"image_format": "PNG" // 默认值
}
可选值：
PNG: 无损压缩，支持透明通道JPG: 有损压缩，文件体积更小WEBP: 现代格式，压缩效率更高ORIGINAL: 保持原始格式
技术细节：格式转换使用Pillow库实现，转换过程中会自动调整色彩空间和压缩参数
媒体下载开关
通过布尔值控制不同类型内容的下载行为：
{
"image_download": true, // 下载图片
"video_download": true, // 下载视频
"live_download": false // 下载直播回放(默认关闭)
}
高级配置技巧
条件下载规则
虽然配置文件本身不支持复杂条件逻辑，但可以通过组合多个配置项实现灵活控制：
{
"author_archive": true, // 按作者创建独立文件夹
"folder_mode": true, // 为每个作品创建独立文件夹
"name_format": "{序号} {标题}" // 简化文件名(因已按作者分类)
}
上述配置会生成如下文件结构：
Download/
├── 美食家小王/
│ ├── 上海必吃的10家老字号/
│ │ ├── 01 招牌菜.jpg
│ │ ├── 02 店内环境.jpg
│ ├── 自制蛋糕教程/
│ │ ├── 01 准备材料.jpg
│ │ ├── 02 烘焙过程.jpg
├── 旅行摄影师小李/
│ ├── 厦门鼓浪屿游记/
│ │ ├── 01 海边日出.jpg
│ │ └── 视频.mp4
网络请求优化
配置文件中的网络相关参数可帮助优化下载体验：
{
"timeout": 15, // 超时时间(秒)，建议10-30
"max_retry": 3, // 失败重试次数
"proxy": "http://127.0.0.1:7890", // 代理设置
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..." // 自定义UA
}
性能提示：对于网络不稳定的环境，建议增加
timeout值并减少chunk大小：{ "timeout": 30, "chunk": 1024*1024 // 将默认2MB块大小减小为1MB }
配置文件迁移与备份
当需要在多台设备间同步配置或备份设置时，可以使用配置迁移功能：
XHS-Downloader会自动检测并迁移旧版本的配置文件：
# 配置迁移核心代码
if old_path.exists() and not new_path.exists():
shutil.move(old_path, new_path)
配置故障排除
常见配置问题解决
配置文件无法保存
通常是由于权限问题导致，解决方案：
- 检查目标文件夹的写入权限
- 尝试以管理员身份运行程序
- 手动创建配置文件并设置正确权限
下载路径不生效
排查步骤：
- 确认路径是否存在且可写
- 检查是否包含特殊字符
- 验证路径格式是否正确(特别是Windows系统的反斜杠)
文件名乱码
解决方法：
{
"name_format": "作品ID {作品ID}" // 使用纯ASCII字符的命名格式
}
配置重置与恢复
当配置出现严重问题时，可以通过删除settings.json文件强制程序生成新的默认配置。或使用备份恢复：
总结与最佳实践
推荐配置组合
内容收藏家方案：
{
"work_path": "~/Documents/XHS-Collection",
"folder_name": "{作者昵称}",
"name_format": "{发布时间} {标题}",
"author_archive": true,
"record_data": true
}
轻量下载方案：
{
"work_path": "", // 使用默认路径
"folder_name": "XHS-Downloads",
"name_format": "{作品ID}", // 简洁命名
"image_format": "WEBP", // 节省空间
"download_record": false // 不记录下载历史
}
配置优化建议
- 路径规划：使用多级目录结构，如
{年份}/{月份}/{作者} - 命名策略：包含作品ID确保唯一性，如
{作品ID} {标题} - 格式选择：存储空间有限时优先使用WEBP/JPG格式
- 定期备份：重要配置定期导出备份，避免意外丢失
通过本文介绍的配置选项，你可以完全掌控XHS-Downloader的下载行为，打造个性化的内容管理系统。随着项目的不断发展，配置系统也将支持更多高级功能，敬请关注项目的更新日志。
最后，如果你有独特的配置需求或创意用法，欢迎在项目GitHub仓库分享你的经验！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
