在线播放插件

瓜子音乐通过插件系统支持在线音乐播放。首次使用在线播放功能时，需要安装官方提供的播放插件。

重要

插件是播放在线音乐的必要条件。未安装或失效时，仅在线播放会受影响--本地扫描、WebDAV、已下载歌曲均不受影响。

为什么需要插件？

播放插件包含各音乐平台的最新接口适配逻辑。为了保持和平台接口的兼容性，插件需要定期更新。瓜子音乐的核心程序不变，通过更新插件来适应平台变化。

这种设计的好处：

• 平台接口变化时无需更新整个 App：只需更新插件即可
• 更新体积小：插件通常只有几十 KB，比下载整个安装包快得多
• 稳定可靠：核心播放逻辑与平台适配解耦，互不影响

安装插件

第一步：获取插件

1. 打开瓜子音乐，进入 设置 -> 插件
2. 点击 下载插件 按钮
3. 插件文件（.gzplugin）会自动下载到本地

通用插件

当前下载的插件为通用插件，所有用户导入同一份文件。这份插件由 M7 后台统一管理生成，确保安全和最新。

第二步：导入插件

1. 在 设置 -> 插件 页面点击 导入插件
2. 选择下载好的 .gzplugin 文件
3. 系统自动校验插件签名与有效性
4. 导入成功后即可正常播放在线音乐

导入条件

• 必须已登录瓜子音乐账号
• 插件文件必须为 .gzplugin 格式
• 插件签名必须有效（防止被篡改）

插件状态

在 设置 -> 插件 页面可以看到当前插件状态：

状态	说明	在线播放
已启用	插件正常，版本有效	可用
已停用	插件被后台停用	不可用
已过期	当前版本已过期，需要更新	不可用
未安装	未导入任何插件	不可用
已失效	后台已重新生成新版本，旧版失效	不可用

不受影响的功能

插件状态异常时，本地音乐、WebDAV 音乐、已下载歌曲均不受影响，可正常播放。

更新插件

当有新版插件发布时：

1. 启动瓜子音乐时会自动检测插件状态
2. 如果提示插件过期，前往 设置 -> 插件 手动下载新版本
3. 导入新版本后旧版本自动失效

你也可以随时在 设置 -> 插件 中点击 检查状态 来手动检测。

更新频率

插件更新频率取决于各音乐平台接口的稳定性，通常每月 1-3 次。建议开启自动检查，及时更新获得稳定体验。

插件工作机制

• 签名校验：每个插件都有官方 RSA 签名，导入时校验签名确保未被篡改
• 本地存储：插件文件存储在本地 userData 目录中
• 门禁拦截：主进程在取链、解密等关键 IPC 调用时检查插件状态，未通过则拒绝
• 后台禁用 / 重新生成：M7 后台管理员可禁用或重新生成插件，用户下次启动（或手动检查状态）后生效

洛雪音源

除了内置插件，瓜子音乐还兼容第三方 洛雪音源，导入洛雪社区维护的自定义源脚本后，可进一步扩展在线播放的音源渠道。

两者关系

• 内置插件：官方维护，所有用户共用同一份，覆盖六大平台
• 洛雪音源：第三方社区维护，用户自行导入，作为内置音源的补充
• 两者互补，可同时使用

常见问题

没有插件能播放在线音乐吗？

• 不能。插件是播放在线音乐的必要条件
• 本地和 WebDAV 音乐不需要插件
• 已下载的歌曲作为本地文件播放，也不需要插件

插件从哪下载？

• 只能通过瓜子音乐客户端内置的下载功能获取
• 确保插件来源安全可靠
• 不要从第三方渠道下载 .gzplugin 文件，可能被篡改

导入插件失败？

• 确认文件完整（.gzplugin 后缀）
• 确认已登录瓜子音乐账号
• 确认文件未被修改或损坏
• 检查文件是否为最新下载的版本
• 重新下载一次再尝试导入

插件状态显示「已失效」？

• 后台已重新生成新版本，旧版被标记为失效
• 重新下载并导入最新版本即可

插件不影响哪些功能？

• 本地音乐扫描和播放
• WebDAV 远程音乐播放
• 已下载的歌曲播放
• 歌单编辑和整理
• 本地歌词文件读取

在线播放时被拦截并提示「插件未通过」？

• 检查插件状态（设置 -> 插件）
• 重新导入或更新插件
• 如插件状态正常但仍被拦截，重启瓜子音乐后重试
• 播放过程不会重复查 status，仅在启动 / 登录时检查