音源初始化失败的常见原因与排查步骤

音源的四种状态

在自定义源管理界面，每个音源可能显示以下状态：

目标是让音源达到「初始化成功」。

排查步骤

1. 确认文件格式

音源脚本必须是 UTF-8 编码的 .js 文件。检查以下几点：

• 文件扩展名：必须是 .js。如果你从压缩包里解压出来的文件是 .txt 或无扩展名，需要手动重命名。
• 编码：文件不能是 GBK 或其他编码。可以用 VS Code 打开文件，查看右下角的编码标识，必要时转换为 UTF-8。
• 文件路径：避免路径中包含中文或特殊字符（虽然不是硬性要求，但某些情况下会导致加载失败）。

2. 确认脚本元信息完整

打开 .js 文件，开头应该有一段注释：

/**
 * @name 音源显示名称
 * @description 简介
 * @version 1.0.0
 * @author 作者
 * @homepage URL
 */

如果这段注释缺失或格式错误，宿主可能无法正确解析音源信息。

3. 查看错误日志

桌面版可以打开开发者工具查看更详细的错误信息：

• 按 Ctrl + Shift + I（或 Cmd + Option + I）打开开发者工具。
• 切换到 Console 标签页。
• 重新勾选音源，观察 Console 中的报错信息。

常见的错误类型：

4. 检查宿主版本

某些音源脚本可能依赖较新版本的宿主 API。如果你还在用旧版本的洛雪音乐桌面版，可能不兼容较新的音源脚本。

• 桌面版从 v2.6.0 起移除了所有内置源，导入的脚本需要面向这个版本之后的 API。
• 检查软件设置中的版本号，与音源脚本的文档说明对照。

5. 确认网络连接

音源脚本初始化时可能需要发起 HTTP 请求（比如从远程拉取配置或测试接口连通性）。确认：

• 电脑/手机的网络连接正常。
• 防火墙没有拦截洛雪音乐的网络请求。
• 如果你使用了代理或 VPN，确认代理配置不会影响洛雪音乐的请求。

6. 尝试其他音源

如果单个音源脚本反复初始化失败，可能是这个脚本本身有问题，不是你的操作错误。快速验证方法：

• 换一个音源脚本试试。
• 如果多个脚本都失败，可能是宿主版本问题或网络问题。
• 如果其他脚本能成功，说明这个特定的脚本已损坏、失效或与你的宿主版本不兼容。

7. 清理残留记录

如果反复导入同一个文件但状态一直不对，可以尝试：

1. 在自定义源管理界面删除该音源的记录。
2. 完全退出洛雪音乐（包括托盘图标）。
3. 重新启动洛雪音乐。
4. 再次导入脚本。

初始化成功后搜索仍为空

如果音源显示「初始化成功」但搜索还是没有结果：

1. 确认音源已勾选启用。
2. 在「音乐来源」设置中，确认已将该音源设为默认搜索源。
3. 搜索时留意是否有其他音源也在并行搜索，可能其他音源的返回结果被合并或优先级更高。
4. 尝试切换到单音源模式（只启用这一个音源），排除多音源干扰。
5. 清除洛雪音乐的缓存后重试。

音源脚本可能已失效

即使初始化成功，音源也可能因为以下原因而无法返回数据：

• 第三方平台接口变更。
• 反爬机制升级。
• 脚本作者停止维护。

判断方式：初始化成功后，实际播放歌曲时会显示「换源失败」。此时换一个音源脚本即可。

相关阅读

• 导入第一个音源 —— 完整的导入步骤。
• 切换与回退机制 —— 多个音源并行时的调度逻辑。
• 自定义源脚本编写指南 —— 自己写脚本时的 API 参考。