res-downloader 抓包下载失败完整排查指南：按链路环节逐级定位修复

res-downloader 抓包下载失败完整排查指南：按链路环节逐级定位修复

【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader

res-downloader 是一款基于代理抓包的网络资源下载器：流量先经过本地代理，工具从中筛出视频号、抖音、m3u8、直播流等可用资源，下载到本地磁盘，落盘前还会做一遍文件完整性校验。做 res-downloader 下载失败排查，最省事的办法是先判断卡在哪一段——问题一般只出在四个环节之一：落盘、分片下载、完整性校验、抓取。环节定位对了，修复动作基本就唯一了。

落盘环节：查磁盘空间、查保存目录和权限

现象：进度条走到一半报写盘失败

日志或界面上出现write file failed at offset 123456789: no space left on device，意思是"在偏移量某处往磁盘写数据时失败了，原因是设备空间不足"。也可能见到create directory failed: permission denied（创建目标目录失败）或file open failed: …（打开目标文件失败）。

定位：为什么该怀疑落盘

落盘是整条链路的最后一公里，此时数据已经从网络拿回来了，剩下的只是写进本地文件。res-downloader 会先把目标文件按完整大小Truncate占位、再按分片写入，所以磁盘剩余空间不够、目录不可写、保存路径指向了未挂载的盘，都会在这一步翻车。凡是报错里带write、open、truncate字样的，先按本地存储问题处理。

动作：改保存目录、清出空间

🔧 打开设置页，检查"保存位置"（对应字段SaveDirectory，默认是~/Downloads，定义在 core/config.go），把它改到一个空间充足、你有写权限的目录；顺手看一眼系统磁盘剩余容量，必要时清理一下。

验证：文件完整落盘

重新下载，不再出现no space left on device，文件出现在新目录里，大小与列表中"资源大小"一致，能正常打开。

分片下载环节：查 Range 请求、调任务数断流补下

现象：读到一半断流，重试三次仍失败

常见报错有三句：read response failed: …（读取服务端响应流时中断）；Task 0 failed (attempt 1/3): …（某个分片第 1 次尝试失败，后面还会有 2、3 次）；以及重试耗尽后的task 0 failed after 3 attempts: read response failed: …。另一种是server does not support range requests, status: 200——服务端不支持按字节区间取文件。

定位：Range 请求决定能不能分片

分片下载就是把文件切成几段并行下载，每段只负责一小块字节。它依赖 HTTP 的 Range 请求：只有服务端返回Accept-Ranges: bytes且文件大于 1MB（MinPartSize）时才会自动分段，逻辑在 core/downloader.go 的createDownloadTasks。如果源站只回 200 而不给 206（Partial Content），说明它根本不接 Range，分片策略对它无效，报的就是那句server does not support range requests。单次分片的重试上限和间隔是写死的：

MaxRetries = 3 // 最大重试次数 RetryDelay = 3 * time.Second // 重试延迟

网络抖一下，某个分片断流，就会看到Task N failed (attempt 1/3)然后隔 3 秒自动补下，三次都失败才整体报错。

动作：调大任务数，或让整段兜底

🔧 断流频繁的（大文件、弱网）：在设置页把"连接数"调大（字段TaskNumber，默认 CPU 核数 ×2，见 frontend/src/views/setting.vue），切段越多、每段越小，断了只需补下一小段。遇到server does not support range requests的：不必硬扛，代码在分片失败后会自动降级为单任务整段重下，等它走完整段即可；若反复失败，换个网络或稍后再试。

验证：进度走完不再卡 99%

日志里Task N failed (attempt 1/3)出现后自动重试并继续，或者自动降级整段下载后，进度条按整段走到 100%，不再反复刷range requests报错。

完整性校验环节：查分片是否下全、文件是否读得到

现象：进度显示完成，却提示校验没通过

下完后报task 0 not completed（某个分片没有被标记为完成），或get file info failed: …（获取文件信息失败，即文件读不到）。

定位：校验查的是"齐"和"读得到"

所有分片写完之后，core/downloader.go 里的verifyDownload会做两件事：逐个确认每个任务都标记了isCompleted，再对文件做一次Stat，确认文件真实存在且可读。文件在写入过程中被别的程序占用、杀毒软件把新建文件隔离了、或磁盘状态异常导致有洞没补上，都会让这一步不通过。另外提醒一句：中途手动取消任务时，半成品文件会被自动删除，不会留下 0 字节残件。

动作：清掉残件，重新下载

⚠️ 到保存目录删掉对应残件（确认没有别的程序在读它），然后在资源列表对该项重新发起下载。校验失败时文件本身已不可用，不必反复重试同一个残件。

验证：校验通过、文件可用

日志不再出现task N not completed，最终文件大小与资源标注一致，播放器能完整播放、不再提示文件损坏。

抓取环节：装好系统证书、确认代理端口 127.0.0.1:8899

现象：列表始终没有资源，或提示"不是私密链接"

打开视频号、小程序等场景后，资源列表一直是空的，或出现"链接不是私密链接"的提示。

定位：抓包是整条链路的起点

res-downloader 以本地代理方式工作，默认监听127.0.0.1:8899（Host和Port见 core/config.go）。系统流量必须走这个代理，并且工具要能解密 HTTPS 内容——这依赖它自带的 CA 证书被安装为"受信任的根证书"。证书没装对，HTTPS 流量就是解不开的密文，表现就是拦截不到资源；代理端口没指对，流量压根不经过它。

动作：装证书、指对代理

✅ 在软件左下角"？"里下载最新证书，按系统安装到受信任的根证书；Mac 手动安装可参考 docs/troubleshooting.md：

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /Users/$(whoami)/Library/Preferences/res-downloader/cert.crt

同时把系统代理设为127.0.0.1:8899，并确认防火墙没有拦截本机端口。装完证书仍反复提示安装的，按 troubleshooting 里"安装证书后还会提示安装"一节补一个锁文件即可。

验证：资源能抓出来

再次打开视频号、抖音等场景，资源列表新增条目，"状态"列显示就绪/完成，下载链路后续环节即可正常工作。

一张表收口：现象对号入座

环境安装参考 docs/installation.md，资源获取流程参考 docs/examples.md。res-downloader 的分片与校验逻辑仍在持续迭代，建议定期更新到最新版本——不少下载失败在新版里已经直接修掉了。

【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader