Spotube 插件加载失败——从 .smplug 到 Zipline 沙箱的排查
症状分类
Spotube 插件加载失败的表现：
| 表现 | 可能原因 |
|---|---|
| 插件页"可用插件"里能看到，但 "Install" 后没反应 | .smplug 下载损坏 / 路径权限 |
| 插件在"已安装"里，但开关一打就红并报错 | plugin.json manifest 格式错误 / 接口签名不匹配 |
| 启用后 Spotube 立即闪退 | 插件 main() 函数崩溃（空指针 / Bridge 调用失败） |
| 启用成功但搜索/播放调用不到 | 插件注册的接口没有对应实现 |
| 运行时偶发崩溃 | 插件 HTTP 请求异常 / Zipline 沙箱内存不足 |
排查步骤
1. 确认插件文件完整
插件目录里找到 .smplug：
- 文件大小正常吗？（通常几十 KB ~ 几百 KB）
- 如果只有几 KB 或 0 字节 → 下载损坏，删了重下
- 手动解压（改扩展名成 .zip）→ 里面应该有
plugin.json+index.zipline.js
2. 确认版本兼容
plugin_interfaces 版本必须匹配 Spotube 主版本：
| Spotube 版本 | 兼容的 plugin_interfaces 版本 |
|---|---|
| v5.0.x | 5.0.x |
| v5.1.x | 5.1.x |
v5.1 新增了几个接口方法（比如 AudioAPI 新增了 FLAC codec 声明），v5.0 的插件直接装到 v5.1 上大概率会出问题。反过来 v5.1 的插件装到 v5.0 上也会因为旧版宿主缺少新 Bridge 方法而崩溃。
解法：让插件作者发布对应版本的 .smplug；或在 Spotube 上先装匹配版本的插件。
3. 看 debug log
Spotube 设置 → Debug → Export debug log。插件加载成功和失败的日志都会出现在里面，关键字：
- 搜索 "plugin" → Spotube 加载插件时的所有信息
- 搜索 "Zipline" → Zipline runtime 的初始化和插件注册日志
- 搜索 "ERROR" / "Exception" → 插件崩溃或 Bridge 调用失败的堆栈
4. 开发者模式（桌面端）
spotube --developer-mode开发者模式会在 Spotube 里显示：
- 每个插件的加载耗时
- 每个 Bridge 调用的耗时和状态
- Zipline 沙箱的内存占用
5. 用示例插件验证宿主没坏
Spotube 仓库的 js_plugin_example/ 里有一个最小示例插件。编译它：
git clone KRTirtho/spotube
cd spotube/js_plugin_example
./gradlew spotubePlugin
# 得到 my-plugin-1.0.0.smplug把这个最小插件装到 Spotube。如果这个也加载失败 → 问题在你的 Spotube 安装或系统环境（不是你想装的那个插件）。如果这个能加载 → 问题在那个插件本身（版本 / 代码）。
常见 .smplug 问题
plugin.json 格式错误
plugin.json 必须是合法 JSON，且包含 id / version / name / abilities 字段。少任何一个 Spotube 加载时都会报 "Invalid plugin manifest"。
abilities 字段声明了但接口没实现
plugin.json 里写了 "abilities": ["audio"]，但插件 main() 里只注册了 MetadataSearchAPI → Spotube 以为它有 AudioAPI 能力，调用时崩溃。
index.zipline.js 不是有效 Zipline bundle
有些插件作者忘了用 spotube-gradle-plugin 打包，自己手动把 Kotlin/JS 编译产物扔进去 → 缺少 Zipline 初始化代码，加载失败。
插件需要的 Bridge 能力 Spotube 版本没有
比如插件用了 Spotube v5.1 才有的 AudioAPI codec 声明，但你还在 v5.0 → Bridge 找不到对应方法，崩溃。
插件卸载 / 重装
完全移除插件
- Spotube 插件页 → 开关关掉 → 点删除按钮
- 手动去插件目录把
.smplug文件删掉（Spotube 有时没清干净） - 重启 Spotube
强制重装
- 同版本覆盖：Spotube 插件页点 "Update"（如果有的话）
- 手动替换：关掉 Spotube → 去插件目录删旧文件 → 拷新文件进去 → 启动
向插件作者反馈问题
带这些信息提交 Issue / Discord 消息：
- Spotube 版本号（精确到 nightly build date，如果是 nightly）
- 插件版本号
- 你的操作系统和版本
- debug log 里 "plugin" 和 "Exception" 关键字附近的内容
- 复现步骤（精确：装了什么、点了什么、报了什么错）