Spotube 插件开发入门——Kotlin/JS + Zipline 环境搭建

前置要求

根据 Spotube 官方插件文档 docs.spotube.cc/getting-started，插件开发需要：

工具	最低版本	推荐
Kotlin	2.0+	IntelliJ IDEA 自带
Gradle	8+	IntelliJ IDEA 自带
JDK	17+	推荐 OpenJDK 17 或 21
IDE	IntelliJ IDEA / Android Studio	任何支持 Kotlin 的 IDE
Spotube	v5.1.0+（含 v5.1 的 AudioAPI）	开发和测试插件用

为什么是 Kotlin/JS

Spotube 插件用 Kotlin Multiplatform 的 JS target——Kotlin 代码编译成 JavaScript，在 Zipline（Kotlin/JS runtime）里运行。相比 Dart/Flutter 扩展：

沙箱更安全：Zipline 把插件隔离在独立 JS 虚拟机里，只能通过宿主 Bridge 做事
语言生态更丰富：Kotlin + Gradle 组合比 Dart + pubspec 成熟，JVM 生态可以复用
Zipline runtime：Cash App（Square）开源，专门设计给"宿主 + 插件"模型，有完整的类型安全、错误隔离、生命周期管理

环境搭建步骤

1. 装 JDK 17+

# 推荐用 Temurin 或 Corretto
# macOS / Linux
brew install --cask temurin17

# Windows（winget）
winget install Microsoft.OpenJDK.17

2. 装 IntelliJ IDEA

IntelliJ IDEA Community 版免费，下载后：

Settings → Plugins → 确认 "Kotlin" 插件已启用（默认就是）
Settings → Build → Gradle → Gradle JVM → 选刚装的 JDK 17

3. 克隆 Spotube 示例插件仓库

Spotube 官方在仓库里提供了一个完整的插件示例：

git clone KRTirtho/spotube
# 示例在 js_plugin_example/ 目录下

或直接克隆示例目录（GitHub 的 Subdirectory 方式）。打开项目后 Gradle 会自动下载依赖（plugin_interfaces、zipline、spotube-gradle-plugin）。

4. 跑通第一个构建

在项目根目录执行：

./gradlew spotubePlugin

构建产物会在 build/distributions/ 下出现 .smplug 文件——这就是你的第一个可安装插件！

项目结构（来自 js_plugin_example）

my-plugin/
├── build.gradle.kts
├── plugin.json
└── src/
    └── jsMain/
        └── kotlin/
            └── myplugin/
                ├── main.kt              # 插件入口
                └── plugin_apis/
                    ├── core/            # CoreAPI 实现
                    ├── audio/           # AudioAPI 实现
                    ├── lyrics/          # LyricsAPI 实现
                    ├── scrobble/        # ScrobbleAPI 实现
                    └── metadata/        # MetadataSearchAPI 实现

关键 Gradle 依赖

Spotube 插件需要三个 Maven Central 依赖：

依赖	Group ID	目的
`plugin_interfaces`	`dev.krtirtho.spotube`	Spotube 宿主定义的插件 API 接口 + 数据模型
`zipline`	`app.cash.zipline`	Kotlin/JS 插件 runtime
`spotube-gradle-plugin`	`dev.krtirtho.spotube.gradle-plugin`	把 Kotlin/JS 编译产物 + plugin.json 打包成 `.smplug`

plugin_interfaces 版本号跟随 Spotube 主版本——v5.1.0 对应 v5.1.x，v5.0.0 对应 v5.0.x。

快速验证

构建得到 .smplug → 在 Spotube 插件页点"上传本地插件"
启用插件 → Spotube 立即加载
插件如果实现了 MetadataSearchAPI → 搜索某首歌看结果里有没有你的插件返回的
插件如果实现了 AudioAPI → 播放看音频流是不是来自你的插件

一切正常 = 开发环境就绪。

参考

完整 API 文档：docs.spotube.cc/api/（每个接口的方法签名和返回值说明）
示例插件源码：github.com/KRTirtho/spotube/tree/js_plugin_example
Discord 开发者频道：discord.gg/uJ94vxB6vg → #plugin-dev