res-downloader 下载失败排查：从进度卡 99% 到完整走完 100%
【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader
res-downloader 靠代理抓包筛出视频号、抖音、m3u8、直播流等资源并分片下载，最后落盘做文件完整性校验。res-downloader 下载失败、进度条卡在 99% 时，本文按 网络 → 分片设置 → 磁盘 → 策略回退 的顺序带你排查。
先读懂报错：4 种报错的"人话"翻译
遇到 res-downloader 下载失败，别先动手改设置。把界面上那句报错认出来，基本就知道该怀疑哪一环：
| 报错原文 | 这意味着什么 | 该怀疑哪一环 |
|---|---|---|
task 0 failed after 3 attempts: read response failed: … | 传输到一半断了流，单任务重试 3 次都没救回来 | 网络链路不稳，或服务端在限流，不一定是文件本身的问题 |
server does not support range requests, status: 200 | 这个源不接受"按字节区间取文件"（Range 请求），分片下载策略对它失效 | 源端能力问题，不是你本机的问题 |
write file failed at offset …: no space left on device | 从服务端读到了数据，但写本地磁盘时失败 | 磁盘空间、目录权限、保存路径 |
| 资源列表是空的，或提示"不是私密链接" | 流量没正确经过抓包代理，或 HTTPS 解密没成功 | 系统证书、代理是否指向127.0.0.1:8899 |
按顺序动手排查：网络 → 任务数 → 保存目录 → 策略回退
🔧 四步按顺序来，每一步都有明确的"怎么判断 → 怎么改 → 怎么验"。
① 网络链路和服务端限流先排除
- 怎么判断：日志里先出现
Task N failed (attempt 1/3)，最后定格在task N failed after 3 attempts。这类报错集中在某几个时间段，且换手机热点后好转，多半是链路问题。 - 怎么改：切到更稳定的网络；同一时段用浏览器直接打开该资源，如果同样慢或转圈，就是服务端限流，错峰再试。
- 怎么验：重新下载后，日志里不再出现
Task N failed，或者只闪一下、进度随即恢复。
② 任务数怎么调：让断掉的段补得更快
"任务数"就是分片数：文件被切成几段并行下载，每段只管一小块，断了只补那一块。
- 怎么判断：日志里频繁出现
Task N failed (attempt …)，尤其弱网下大文件更容易整段断流。 - 怎么改：设置界面的"任务数"（对应 frontend/src/views/setting.vue 里的
TaskNumber，默认值是 CPU 核数 ×2，定义在 core/config.go）。调大它，分片就更小、单片断了重下更快；调小则分片更大。单个分片任务的重试上限和间隔是写死的常量，在 core/downloader.go：
MaxRetries = 3 // 最大重试次数 RetryDelay = 3 * time.Second // 重试延迟- 怎么验：日志里
Task N failed (attempt 1/3)出现后 3 秒自动重试，进度不再卡 99%。
③ 保存目录怎么查：空间和可写性
- 怎么判断：日志报
write file failed at offset …，且错误细节指向no space left on device或权限类信息——数据已经下载到了，倒在写盘这一步。 - 怎么改：检查设置里的"保存目录"（字段
SaveDirectory，默认~/Downloads，定义在 core/config.go）：剩余空间是否大于文件大小、该目录是否可写。空间不够就清理，或换一个目录再试。 - 怎么验：再次下载不再出现
write file failed，进度条走完，文件正常出现在保存目录里。
④ 不支持 Range 请求怎么办：走整段下载
- 怎么判断：日志出现
server does not support range requests, status: 200。分片策略依赖服务端回Accept-Ranges: bytes且文件大于 1MB 才会自动生效（逻辑在 core/downloader.go 的createDownloadTasks），源不支持时就不该硬用多段。 - 怎么改：程序自带一次兜底——多段下载出错后会降级成单任务整段重试。如果整段重试仍失败，把"任务数"手动调小到下限（2），按整段下。
- 怎么验：日志不再出现
server does not support range requests，进度条按整段走到 100%。
边界场景：超大文件、弱网和抓不到资源
超大文件 + 弱网：把分片切得更碎
大文件在弱网下整段传输更容易断。最小改动：在设置里把TaskNumber调大，例如TaskNumber = 8。分片更小，单片断流后重下的代价更低，进度恢复得更快。
抓不到资源 / 提示"不是私密链接"：查证书和代理
这类问题的根源不在下载环节，而在抓包环节：
- 确认系统代理指向
127.0.0.1:8899（res-downloader 默认监听地址，见 docs/troubleshooting.md）。 - 确认系统证书已正确安装到受信任根证书。Mac 可在终端执行：
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /Users/$(whoami)/Library/Preferences/res-downloader/cert.crt执行完再打开软件。如果装完仍反复提示"需要安装证书"，按 docs/troubleshooting.md 的说明创建 install.lock 锁文件。
收尾速查表：现象、动作、预期结果
| 现象 | 动作 | 预期结果 |
|---|---|---|
task N failed after 3 attempts，进度卡 99% | 调大"任务数"或换稳定网络 | 重试后进度走完，不再卡 99% |
server does not support range requests | 任务数调至下限，走整段下载 | 进度条按整段走到 100% |
write file failed …: no space left | 清理磁盘或更换"保存目录" | 文件正常落盘 |
| 资源列表为空 / "不是私密链接" | 装好证书，确认代理127.0.0.1:8899 | 资源列表出现可下载的资源 |
✅ res-downloader 的分片与校验逻辑还在持续调整，很多下载失败在新版本里已经修好，遇到反复出现的问题建议先更新到最新版。证书、代理的细节对照 docs/troubleshooting.md，资源获取步骤参考 docs/examples.md，环境搭建看 docs/installation.md。
【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
