3 步自查搞定 res-downloader 下载失败：文件完整性校验排查指南
【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader
res-downloader 靠代理抓包——流量先经过它、再从中筛出资源——把视频号、抖音、m3u8、直播流这些资源抓下来存到本地。下完它还会做一层完整性校验：确认每个分片都下完、文件读得到。可网络抖一下或服务端不给力，这步就容易失败，文件卡在 99% 下不完。这篇带你从屏幕上那几句报错出发，一步步把它修好。
看到什么错，就怀疑哪里：先读懂这几句报错
先别急着改代码，把界面上那一句报错认出来，基本就能定位到该怀疑哪一环：
"task 0 failed after 3 attempts: read response failed: …"——传输到一半断了流，多半是网络链路不稳或服务端限流，不一定是文件本身坏了。"server does not support range requests, status: 200"——这个源不接受"按字节区间取文件"（Range 请求），所以"分片下载"这条策略对它不适用。"write file failed at offset …: no space left on device"——写本地磁盘时失败，该怀疑磁盘空间、权限或保存目录。
一步步修好下载失败：调任务数、查磁盘、换整段
🔧 下面三步，照着做基本就能修好。
把任务数调大，让断掉的段自动补下
做什么：把"任务数"调大，让一个文件被切成更多小段同时下，断了也只需补下其中一段。
在哪做：设置界面的"任务数"（见 setting.vue，对应字段TaskNumber，默认是 CPU 核数 ×2）。它决定分片数——分片下载就是把文件切成几段并行下、每段只管一小块；而单次任务的重试上限与间隔是写死的常量，在 core/downloader.go：
MaxRetries = 3 // 最大重试次数 RetryDelay = 3 * time.Second // 重试延迟怎么确认生效：重新下载，进度不再卡 99%，日志里Task N failed (attempt 1/3)出现后会自动重试并继续走。
查保存目录和磁盘，别在写盘时翻车
做什么：确认保存目录有空间、能写，避免下到一半写盘失败。
在哪做：设置里的"保存目录"（字段SaveDirectory，默认是你的~/Downloads），定义在 core/config.go。
怎么确认生效：再下一次，不再弹write file failed at offset …: no space left on device，文件正常落盘。
遇到不支持分段的源，改走整段下载
做什么：如果报"server does not support range requests"，就别硬用多段，改成单段整段下。
在哪做：把"任务数"调小或直接走单段。分片判断在 core/downloader.go 的createDownloadTasks——只有服务端回Accept-Ranges: bytes且文件大于 1MB 才会自动分段。
怎么确认生效：日志不再出现server does not support range requests，进度条按整段走到 100%。
换个场景：超大文件、弱网和证书
- 超大文件 / 弱网：大文件在弱网下分段更容易断流，把"任务数"调大让每片更小，单片断了重下更快。最小改动：在设置里把
TaskNumber调大，例如TaskNumber = 8。 - 拦截不到 / 提示"不是私密链接"：多半是系统证书没装对，或代理没走
127.0.0.1:8899。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✅ 还卡住的话，对照下面这张表自查：
| 看到的报错 | 该做的动作 | 做完应该看到 |
|---|---|---|
task N failed after 3 attempts | 调大"任务数"或换稳定网络 | 进度走完、不再卡 99% |
server does not support range requests | 调小任务数或整段下载 | 按整段走到 100% |
write file failed …: no space left | 清磁盘或改"保存目录" | 文件正常落盘 |
| 列表看不到资源 / "不是私密链接" | 装好证书、确认代理 127.0.0.1:8899 | 资源列表能抓到资源 |
对照 docs/troubleshooting.md 排证书和代理，配合 docs/examples.md 的资源获取步骤复现，装环境看 docs/installation.md。res-downloader 的分片与校验逻辑还在持续调整，建议定期把软件更新到最新版，很多下载失败在新版本里已经被修掉。
【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
