下载失败排查：音源、权限、磁盘空间

症状

点击下载后：

• 进度条很快停住不动
• 提示下载失败
• 下载队列里标记为红色

桌面端独有的功能

首先确认你是在桌面端：下载功能目前只有 Windows / macOS / Linux 桌面端支持，安卓和网页端不能下载（这不是 bug，是功能边界）。

排查步骤

第一步：磁盘空间

最简单的检查：

• 下载目录所在磁盘还有多少可用空间？
• 无损格式每首歌 30-50MB，批量下载时空间消耗很快
• macOS 的用户数据目录在系统盘上，注意系统盘空间

第二步：下载目录权限

• Windows：当前用户是否对下载目录有写权限？
• macOS：「下载」文件夹是否被其他应用锁了？
• Linux：检查 ls -ld 下载目录 的权限位

临时换一个目录试试（比如桌面）。

第三步：音源问题

灰色歌曲的下载依赖灰色解析的音源。如果灰色解析本身失败，下载也会失败。

1. 先确认这首歌能播放（灰色解析成功）
2. 能播放但不能下载 → 音源可能只提供流式播放、不允许下载
3. 手动换个音源再试下载

第四步：VIP 权限

某些无损音质下载需要网易云 VIP 登录：

• 确保已登录正确的 VIP 账号
• 如果是灰色解析拿到的音源，该音源是否提供无损？

第五步：文件名冲突

同名歌曲下载时可能因为文件名已存在而跳过。设置 → 下载 → 冲突处理策略：

• 跳过（默认）
• 覆盖
• 重命名（自动加后缀）

建议改「重命名」避免跳过。

第六步：网络中断

下载中途断网：

• 下载进度条卡死
• 重连网络后需要重新点下载（当前版本不支持断点续传）

v5.1.0 缓存优化

v5.1.0 重构了音乐和歌词缓存逻辑，支持可配置缓存目录。设置下载路径时注意：

• 缓存目录和下载目录可以分开设置
• 缓存文件不会被自动清理（磁盘满时需要手动清）

仍未解决

按顺序尝试：

1. 重启应用
2. 换一个下载目录（如桌面）
3. 手动换音源
4. 完全清理缓存后重下
5. GitHub Issue 反馈（说明歌曲名、错误提示、尝试过的方案）