3 步修好 res-downloader 下载失败：文件完整性校验报错自查指南
【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader
res-downloader 靠代理抓包，把视频号、直播流、m3u8 这类资源抓下来存到本地，下完还会做一层完整性校验：确认每个分片都下完、文件读得到。网络抖一下、服务端不给力或磁盘写满，这类下载失败就容易发生，进度常常卡在 99%。本文带你走完"读懂报错 → 3 步修复 → 速查表自查"的主线，把 res-downloader 下载失败卡在哪儿找出来、修好。
报错原文对着看：先圈出问题出在哪一环
先别急着改配置或重启软件，把界面上的报错认出来，基本就能定位到该怀疑哪一环：
task 0 failed after 3 attempts: read response failed: …——传输到一半断了流，任务已经重试满 3 次还没救回来，多半是网络链路不稳或服务端限流，不一定是文件本身坏了。server does not support range requests, status: 200——Range 请求是让服务端按字节区间发文件，服务端对区间请求回了 200，说明它不按规格来，分片下载策略对这个源就不成立。write file failed at offset …: no space left on device——往本地磁盘写数据时失败了，该怀疑磁盘空间、目录权限或保存路径。
三步修好下载失败：调连接数、查磁盘、看降级
🔧 下面三步，照着做基本就能修好。
第一步：调大"连接数"，让断掉的段自动补下
做什么：把设置里的"连接数"调大，分片数跟着增加，一个文件被切成更多小段并行下，断了一段只需补下那一段。
在哪做：设置界面的"连接数"（字段TaskNumber），默认是 CPU 核数 × 2，可输入范围 2~64，界面在 frontend/src/views/setting.vue。单任务的重试上限与间隔是写死的常量，在 core/downloader.go：
MaxRetries = 3 // 最大重试次数 RetryDelay = 3 * time.Second // 重试延迟怎么确认生效：重新下载，进度不再卡 99%，日志出现Task 1 failed (attempt 1/3)后会自动重试并继续走。
第二步：查保存目录与磁盘，别让写盘翻车
做什么：确认保存目录有空间、能写，避免下到一半写盘失败。
在哪做：设置里的"保存位置"（字段SaveDirectory），默认是系统~/Downloads目录（Linux 下若设置了XDG_DOWNLOAD_DIR环境变量则优先用它），字段定义与默认值见 core/config.go。
怎么确认生效：再下一次，不再弹write file failed at offset …: no space left on device，文件正常落盘。
第三步：源不支持分段时，降并发、等自动降级
做什么：如果反复出现server does not support range requests，就别硬用大量分片——这个源对 Range 支持不可靠，少分段或整段下更稳。
在哪做：分片判断在 core/downloader.go 的init和createDownloadTasks里——只有服务端回了Accept-Ranges: bytes头且文件大于 1MB（常量MinPartSize）才会自动分段。
怎么确认生效：res-downloader 内置了降级逻辑，分片任务失败后会自动切回单任务整段重下，所以看到这条报错多半最终能下完、只是更慢；若量大，把"连接数"调小降低并发压力，或换稳定的源，进度就能按整段走到 100%。
边界场景：弱网超大文件与"拦截不到资源"
- 超大文件 / 弱网：大文件在弱网下分段更容易断流，把分片切小、并发拉满——"连接数"调到上限 64，单片断了只需补一小段。最小改动：只动设置里的
TaskNumber。 - 拦截不到资源 / 提示"链接不是私密链接"：多半是系统证书没装对，或代理没走
127.0.0.1:8899（Host与Port的默认值正是这两项）。证书安装与代理细节见 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速查表：报错、动作、预期结果逐条对照
✅ 还卡住的话，对照这张表逐条自查：
| 看到的报错 | 该做的动作 | 做完应该看到 |
|---|---|---|
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。res-downloader 的分片与完整性校验逻辑还在持续调整，建议更新到最新版，很多下载失败在新版本里已经被修掉。
【免费下载链接】res-downloader视频号、小程序、抖音、快手、小红书、直播流、m3u8、酷狗、QQ音乐等常见网络资源下载!项目地址: https://gitcode.com/GitHub_Trending/re/res-downloader
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
