小红书下载器 XHS-Downloader 进阶配置手册自定义命名、并发调优与异常兜底【免费下载链接】XHS-Downloader小红书XiaoHongShu、RedNote链接提取/作品采集工具提取账号发布、收藏、点赞、专辑作品链接提取搜索结果作品、用户链接采集小红书作品信息提取小红书作品下载地址下载小红书作品文件项目地址: https://gitcode.com/gh_mirrors/xh/XHS-DownloaderXHS-Downloader 是一款小红书作品下载器与采集工具能提取账号发布、收藏、点赞、专辑及搜索结果的链接采集作品信息并下载媒体文件。本文覆盖name_format、author_archive、MAX_WORKERS、max_retry等配置项回答三个问题下载的文件落盘后长什么样、批量任务如何跑得快又稳、出错时系统如何兜底。 场景一文件落盘 —— 命名变量与作者归档文件名与目录结构由三个参数决定name_format、author_archive、folder_mode均写在settings.json中改完重启程序即可。命名变量支持哪些字段name_format默认值是发布时间 作者昵称 作品标题。注意它只是字段选择器manager.py 的__check_name_format()会按空格切分格式串每个词必须是 13 个保留字段之一运行时代码按选定顺序用_拼接各字段值非法字符统一替换为_总长截断到 128 字符。可用字段包括发布时间、最后更新时间、作者昵称、作者ID、作品标题、作品描述、作品标签、作品类型、作品ID、收藏数量、评论数量、点赞数量、分享数量。若格式串里出现无法识别的词程序会静默回退到默认格式这是命名没生效时最常见的原因。如何开启作者归档与作品分文件夹name_format: 作者昵称 发布时间 作品标题, author_archive: true, folder_mode: trueauthor_archive默认false为每个作者在下发根目录folder_name默认Download下建子文件夹folder_mode默认false让每部作品独占一个以文件名命名的文件夹。两者叠加后图集作品按图片编号落盘为_1、_2视频落盘为单个.mp4Download/ ├── 美食家小明/ │ ├── 美食家小明_2025-06-19 10.30.45_夏日冰饮制作指南.mp4 │ └── 美食家小明_2025-06-20 08.12.09_早餐食谱_1.jpg └── 旅行达人小红/ └── 旅行达人小红_2025-06-21 15.40.22_海岛旅行攻略_1.png⚡ 场景二批量下载如何跑得快又稳并发上限由信号量控制断点续传由 Range 请求实现重复运行天然增量。如何调整并发线程数MAX_WORKERS定义在 static.py默认4被 download.py 的Download.SEMAPHORE消费即同一时刻最多 4 个文件在传输。它不在settings.json里直接修改源码# source/module/static.py MAX_WORKERS: int 8 # 默认 4带宽充足时可上调断点续传与增量下载机制如何工作我们先把文件流式写入Temp目录再移动到目标位置。__update_headers_range()在每次下载前读取 temp 文件当前大小在请求头写入Range: bytes{偏移量}-服务端接受时从中断处继续若服务端返回 416偏移量越界程序判定缓存损坏删除 temp 文件并整份重下。下载成功后文件移入目标目录再次运行同一链接时__check_exists_path()发现目标文件已存在直接打印文件已存在跳过下载不会重复占流量。TUI 还提供选择下载入口按作品索引指定要下载的图片序号最终传入__ready_download_image()过滤用于只补下缺图的作品下载过程中的文件名、百分比与速度由 progress.py 的进度条实时呈现️ 场景三异常与边界 —— 格式纠错、命名冲突与重试系统对坏文件有三道防线魔数改后缀、按文件重试、启动期代理校验。文件格式自动纠错如何工作__suffix_with_file()读取落盘文件前若干字节与 static.py 中FILE_SIGNATURES签名表比对覆盖 jpeg、png、avif、heic、webp、mp4、m4v、mov、mkv、mpg、flv、avi命中即决定最终扩展名全部不命中才保留默认后缀。也就是说CDN 返回的扩展名错误不会落盘image_format默认JPEG可选auto/png/webp/jpeg/heic/avif非法值回退jpeg只决定期望的默认后缀。如何配置重试与代理max_retry默认5tools.py 的retry()装饰器让单文件下载失败后按此次数重跑超限才记为失败。proxy默认None程序启动时先经代理向小红书首页发一次测试请求超时或失败会打印警告并丢弃该代理配置退回直连——看到代理测试失败提示时本次运行实际并未走代理。命名冲突同名文件不会自动加序号__check_exists_path()的行为是直接跳过。要区分同名作品请在name_format中加入作品ID或发布时间。场景四调优自检 —— 参数速查与验证清单参数速查优先调哪些配置参数默认值建议值影响name_format发布时间 作者昵称 作品标题追加作品ID防同名最终文件名与字段顺序author_archivefalse大批量收藏设为true是否按作者建子文件夹folder_modefalse混下多作品时设true每部作品是否独占文件夹MAX_WORKERS48改 static.py同时传输的文件数chunk2MB大文件4MB每次流式读写字节块max_retry5弱网8-10单文件失败重试次数timeout10s弱网15-20s单请求超时时间image_formatJPEGauto保留源格式图文作品默认后缀write_mtimefalse按时间整理时true以作品时间戳作为文件修改时间proxynull已验证的代理地址请求与下载流量全走代理配置验证如何确认改对了改完name_format后下载一部作品核对落盘文件名是否为字段值用_拼接的结构而不是你以为的分隔符写法。启动日志若出现代理测试超时/失败说明本次为直连先修代理再继续批量任务。中断一次下载后检查Temp目录是否有残留 temp 文件重跑同一链接时应从断点续写而非从零开始。开启download_record后重复运行已下载的作品日志应出现文件已存在跳过下载说明增量去重生效。下一步动作克隆源码扩展命名字段在 manager.py 的NAME_KEYS元组中新增字段名并在转换逻辑中补齐对应数据即可让name_format支持自定义字段。利用mapping_data账号备注映射把作者昵称替换为自定义别名按作者归档时目录名随之变化适合按内容主题二次分类。遇到解析失败或反爬变化时将请求头与报错日志整理后提交到项目社区帮助维护者定位。git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader【免费下载链接】XHS-Downloader小红书XiaoHongShu、RedNote链接提取/作品采集工具提取账号发布、收藏、点赞、专辑作品链接提取搜索结果作品、用户链接采集小红书作品信息提取小红书作品下载地址下载小红书作品文件项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 小红书下载器 XHS-Downloader 进阶配置手册：自定义命名、并发调优与异常兜底
小红书下载器 XHS-Downloader 进阶配置手册自定义命名、并发调优与异常兜底【免费下载链接】XHS-Downloader小红书XiaoHongShu、RedNote链接提取/作品采集工具提取账号发布、收藏、点赞、专辑作品链接提取搜索结果作品、用户链接采集小红书作品信息提取小红书作品下载地址下载小红书作品文件项目地址: https://gitcode.com/gh_mirrors/xh/XHS-DownloaderXHS-Downloader 是一款小红书作品下载器与采集工具能提取账号发布、收藏、点赞、专辑及搜索结果的链接采集作品信息并下载媒体文件。本文覆盖name_format、author_archive、MAX_WORKERS、max_retry等配置项回答三个问题下载的文件落盘后长什么样、批量任务如何跑得快又稳、出错时系统如何兜底。 场景一文件落盘 —— 命名变量与作者归档文件名与目录结构由三个参数决定name_format、author_archive、folder_mode均写在settings.json中改完重启程序即可。命名变量支持哪些字段name_format默认值是发布时间 作者昵称 作品标题。注意它只是字段选择器manager.py 的__check_name_format()会按空格切分格式串每个词必须是 13 个保留字段之一运行时代码按选定顺序用_拼接各字段值非法字符统一替换为_总长截断到 128 字符。可用字段包括发布时间、最后更新时间、作者昵称、作者ID、作品标题、作品描述、作品标签、作品类型、作品ID、收藏数量、评论数量、点赞数量、分享数量。若格式串里出现无法识别的词程序会静默回退到默认格式这是命名没生效时最常见的原因。如何开启作者归档与作品分文件夹name_format: 作者昵称 发布时间 作品标题, author_archive: true, folder_mode: trueauthor_archive默认false为每个作者在下发根目录folder_name默认Download下建子文件夹folder_mode默认false让每部作品独占一个以文件名命名的文件夹。两者叠加后图集作品按图片编号落盘为_1、_2视频落盘为单个.mp4Download/ ├── 美食家小明/ │ ├── 美食家小明_2025-06-19 10.30.45_夏日冰饮制作指南.mp4 │ └── 美食家小明_2025-06-20 08.12.09_早餐食谱_1.jpg └── 旅行达人小红/ └── 旅行达人小红_2025-06-21 15.40.22_海岛旅行攻略_1.png⚡ 场景二批量下载如何跑得快又稳并发上限由信号量控制断点续传由 Range 请求实现重复运行天然增量。如何调整并发线程数MAX_WORKERS定义在 static.py默认4被 download.py 的Download.SEMAPHORE消费即同一时刻最多 4 个文件在传输。它不在settings.json里直接修改源码# source/module/static.py MAX_WORKERS: int 8 # 默认 4带宽充足时可上调断点续传与增量下载机制如何工作我们先把文件流式写入Temp目录再移动到目标位置。__update_headers_range()在每次下载前读取 temp 文件当前大小在请求头写入Range: bytes{偏移量}-服务端接受时从中断处继续若服务端返回 416偏移量越界程序判定缓存损坏删除 temp 文件并整份重下。下载成功后文件移入目标目录再次运行同一链接时__check_exists_path()发现目标文件已存在直接打印文件已存在跳过下载不会重复占流量。TUI 还提供选择下载入口按作品索引指定要下载的图片序号最终传入__ready_download_image()过滤用于只补下缺图的作品下载过程中的文件名、百分比与速度由 progress.py 的进度条实时呈现️ 场景三异常与边界 —— 格式纠错、命名冲突与重试系统对坏文件有三道防线魔数改后缀、按文件重试、启动期代理校验。文件格式自动纠错如何工作__suffix_with_file()读取落盘文件前若干字节与 static.py 中FILE_SIGNATURES签名表比对覆盖 jpeg、png、avif、heic、webp、mp4、m4v、mov、mkv、mpg、flv、avi命中即决定最终扩展名全部不命中才保留默认后缀。也就是说CDN 返回的扩展名错误不会落盘image_format默认JPEG可选auto/png/webp/jpeg/heic/avif非法值回退jpeg只决定期望的默认后缀。如何配置重试与代理max_retry默认5tools.py 的retry()装饰器让单文件下载失败后按此次数重跑超限才记为失败。proxy默认None程序启动时先经代理向小红书首页发一次测试请求超时或失败会打印警告并丢弃该代理配置退回直连——看到代理测试失败提示时本次运行实际并未走代理。命名冲突同名文件不会自动加序号__check_exists_path()的行为是直接跳过。要区分同名作品请在name_format中加入作品ID或发布时间。场景四调优自检 —— 参数速查与验证清单参数速查优先调哪些配置参数默认值建议值影响name_format发布时间 作者昵称 作品标题追加作品ID防同名最终文件名与字段顺序author_archivefalse大批量收藏设为true是否按作者建子文件夹folder_modefalse混下多作品时设true每部作品是否独占文件夹MAX_WORKERS48改 static.py同时传输的文件数chunk2MB大文件4MB每次流式读写字节块max_retry5弱网8-10单文件失败重试次数timeout10s弱网15-20s单请求超时时间image_formatJPEGauto保留源格式图文作品默认后缀write_mtimefalse按时间整理时true以作品时间戳作为文件修改时间proxynull已验证的代理地址请求与下载流量全走代理配置验证如何确认改对了改完name_format后下载一部作品核对落盘文件名是否为字段值用_拼接的结构而不是你以为的分隔符写法。启动日志若出现代理测试超时/失败说明本次为直连先修代理再继续批量任务。中断一次下载后检查Temp目录是否有残留 temp 文件重跑同一链接时应从断点续写而非从零开始。开启download_record后重复运行已下载的作品日志应出现文件已存在跳过下载说明增量去重生效。下一步动作克隆源码扩展命名字段在 manager.py 的NAME_KEYS元组中新增字段名并在转换逻辑中补齐对应数据即可让name_format支持自定义字段。利用mapping_data账号备注映射把作者昵称替换为自定义别名按作者归档时目录名随之变化适合按内容主题二次分类。遇到解析失败或反爬变化时将请求头与报错日志整理后提交到项目社区帮助维护者定位。git clone https://gitcode.com/gh_mirrors/xh/XHS-Downloader【免费下载链接】XHS-Downloader小红书XiaoHongShu、RedNote链接提取/作品采集工具提取账号发布、收藏、点赞、专辑作品链接提取搜索结果作品、用户链接采集小红书作品信息提取小红书作品下载地址下载小红书作品文件项目地址: https://gitcode.com/gh_mirrors/xh/XHS-Downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考