res-downloader 下载失败修复指南：三类报错快速定位，一次改对设置

res-downloader 下载失败修复指南：三类报错快速定位，一次改对设置

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

res-downloader 通过代理抓包把视频号、m3u8、直播流等资源存到本地。下载失败卡在 99%，多半逃不出三类：传输断流、源不支持分段、磁盘写入失败。本文按报错定位，指到具体配置字段，并给出修好的验证信号。

一分钟定位：先判断你属于哪类故障

用界面里的报错信息直接对号入座，不用碰代码：

• 提示"列表看不到资源"或"不是私密链接" → 不是下载问题，是拦截问题，跳到修证书和代理一节；
• 是下载失败的报错，看关键字：
  • read response failed→ 传输中某段断了，看"调大任务数让断掉的段自动补下"；
  • server does not support range requests→ 源拒绝了分段，看"遇到不支持 Range 的源改走整段下载"；
  • no space left on device→ 本地磁盘问题，看"改保存目录并确认磁盘剩余空间"。

这三种下载失败都发生在 core/downloader.go 的分片流程里：文件被切成几段，每段由一个任务负责下完，最后校验文件完整性。知道断在哪一层，改哪里就不会错。

调大任务数让断掉的段自动补下

现象：进度停在 99%，日志出现task 0 failed after 3 attempts: read response failed: …。

根因：多段并行下载时，网络抖动或服务端限流会让某一段中断；单个任务的重试次数是固定常量，重试耗尽该段就判失败：

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

操作：

1. 打开设置界面，找到"任务数"输入框，即 frontend/src/views/setting.vue 里的TaskNumber，取值范围 2–64，默认是 CPU 核数 ×2（定义在 core/config.go）。
2. 改成更大的值，比如 16：段数变多、每段更小，断了只重下那一小段，整体进度不容易卡死。
3. 保存设置后，对该资源重新触发下载。

验证：日志出现Task N failed (attempt 1/3)后自动隔 3 秒重试并继续走，进度不再卡 99%，文件完整度走完 100% 并通过完整性校验。

遇到不支持 Range 的源改走整段下载

现象：日志报server does not support range requests, status: 200。

根因：分片下载靠 Range 请求按字节区间取文件。启动前程序会先发 HEAD 探测，只有响应带Accept-Ranges: bytes且文件大于 1MB 才会切段；这个报错说明源收到分段请求后回了 200 而不是 206，分片策略对它不成立。

操作：

1. 设置里把"任务数"TaskNumber放回最小值 2，不要再调大；
2. 回到资源列表，点该资源操作列的"重试"重新抓取；
3. 仍报同样错误，说明该源完全不配合分段，只能整段取，等源变更或重新分享拿新地址。

验证：日志不再出现server does not support range requests，进度条按整段走到 100%。

改保存目录并确认磁盘剩余空间

现象：报write file failed at offset …: no space left on device。

根因：这个错与网络无关——文件已打开并预留了空间，写到指定偏移时落盘被拒，通常是磁盘满或目录不可写；保存目录对应 core/config.go 的SaveDirectory，默认是~/Downloads。

操作：

1. 查保存目录所在磁盘的剩余空间，确保大于待下载资源的体积；
2. 空间不够就在设置里把"保存目录"改成另一个磁盘；
3. 重新下载，文件会落到新目录。

验证：日志不再出现write file failed，新保存目录中出现文件，体积与资源列表显示一致。

修证书和代理恢复资源拦截

现象：资源列表为空，或链接提示"不是私密链接"。

根因：res-downloader 靠代理127.0.0.1:8899抓流量，HTTPS 资源还要求系统信任它的抓包证书；证书没装进受信任根，私密链接解不开，下载无从谈起。

操作：

1. 确认系统代理指向127.0.0.1，端口8899；
2. 仍提示"不是私密链接"，就把证书手动装为受信任根证书，Mac 在终端执行：

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

验证：重新打开软件后资源列表能抓到资源，下载不再报"不是私密链接"。

防止复发

• 弱网下别把TaskNumber拉满到 64，8–16 这种中间值兼顾速度与断流概率；
• 下大文件前先确认保存目录剩余空间大于文件体积，省得整份重下；
• 首次使用前就装好并信任证书，别等"不是私密链接"弹出再处理。

本文覆盖的是下载启动之后的三类下载失败；如果软件起不来或装完证书仍反复提示，查 docs/troubleshooting.md；想复现抓取与下载流程，参考 docs/examples.md 与 docs/installation.md。res-downloader 的分片与校验逻辑仍在调整，建议定期升级到最新版。

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