Stremio Enhanced 插件开发入门:如何写出你的第一个 .plugin.js
Stremio Enhanced 插件开发入门:如何写出你的第一个 .plugin.js
Stremio Enhanced 是一款基于 Electron 的 Stremio 桌面客户端,支持插件(.plugin.js)与主题。本文带你从零写出第一个 Stremio Enhanced 插件文件,掌握元数据写法、内置 API 调用和安装验证的完整流程,新手也能快速上手。
一、先搞懂:Stremio Enhanced 的插件是什么?
很多人会把 Plugin(插件) 和 Addon(扩展包) 搞混,两者完全不同:
| 类型 | 作用 | 运行位置 |
|---|---|---|
| Addon | 为 Stremio 提供影片目录(catalog)和流媒体源(stream) | Stremio 服务层 |
| Plugin | 为 Stremio 客户端新增功能,如快捷键、界面交互、自动化行为 | Stremio Enhanced 页面内 |
插件本质上是运行在 Stremio 网页界面里的 JavaScript 脚本。启动时,src/core/ModManager.ts 会读取插件文件夹中的所有文件,再由 src/preload/ui/mod/modController.ts 把脚本注入页面执行,并且用作用域包裹,防止插件之间互相污染。
下面这张图就是一个插件的实际效果——AniSkip 插件可以在播放动漫时自动弹出"跳过片头"提示:
二、一个最小可用的 .plugin.js 长什么样
一个 Stremio Enhanced 插件文件由两部分组成:头部元数据注释 + 主体脚本。
以官方示例 examples/slashtosearch.plugin.js 为参考,完整模板如下:
/**
* @name MyFirstPlugin
* @description 我的第一个 Stremio Enhanced 插件:按 / 键快速聚焦搜索框
* @author YourName
* @version 1.0.0
* @updateUrl none
*/
document.addEventListener("keyup", (e) => {
if (e.key === "/") {
document.getElementById("global-search-field").focus();
}
});
就这么简单,10 行左右就能跑起来。下面逐段拆解。
1. 头部元数据:插件的"身份证"
元数据写在 /** ... */ 注释块中,解析逻辑见 src/utils/ExtractMetaData.ts。缺少必填字段时,插件不会出现在设置列表里。
必填字段(定义于 src/interfaces/MetaData.ts):
| 字段 | 说明 |
|---|---|
@name |
插件显示名称 |
@description |
一句话功能描述 |
@author |
作者名 |
@version |
语义化版本号,如 1.0.0 |
可选字段:
| 字段 | 说明 |
|---|---|
@updateUrl |
插件更新地址,指向最新版本的 .plugin.js 原始文件;填 none 则关闭自动更新检查 |
@source |
源码仓库地址 |
@homepage |
项目主页地址 |
@license |
许可证类型 |
💡 小提示:更新机制由 src/core/ModManager.ts 实现——它会定期拉取
@updateUrl指向的新版本,对比版本号后在设置页显示"更新"按钮。
2. 主体脚本:你的插件逻辑
脚本部分就是普通的浏览器 JavaScript,可以直接操作 Stremio 页面的 DOM、监听按键事件、拦截网络请求等。唯一的要求是:文件扩展名必须是 .plugin.js(常量定义见 src/constants/index.ts),放在插件文件夹中才会被识别。
三、进阶:调用内置 StremioEnhancedAPI
插件在加载时会被注入一个专属的 StremioEnhancedAPI 对象(注入逻辑见 src/preload/ui/mod/modController.ts),提供日志、配置、弹窗三类能力,让你的插件更"专业"。
1. 日志输出
StremioEnhancedAPI.logger.info("插件已启动");
StremioEnhancedAPI.logger.warn("检测到未知状态");
StremioEnhancedAPI.logger.error("出错了:" + err.message);
日志会按插件名分组写入本地日志系统(实现见 src/preload/api/pluginLogger.ts),方便排查问题。
2. 注册设置项:给你的插件加"配置面板"
通过 registerSettings 提交一份 schema,设置页中插件卡片右侧会自动出现一个设置按钮,用户可以调整你的插件选项。schema 结构参考 src/interfaces/PluginSettingSchema.ts,校验逻辑见 src/preload/api/settings.ts:
StremioEnhancedAPI.registerSettings([
{
key: "hotkey",
type: "input", // input / toggle / select 三种
label: "快捷键",
description: "按下此键打开搜索框",
defaultValue: "/"
},
{
key: "enabled",
type: "toggle",
label: "启用",
defaultValue: true
}
]);
// 读写配置
const hotkey = await StremioEnhancedAPI.getSetting("hotkey");
await StremioEnhancedAPI.saveSetting("hotkey", "/");
支持 input(文本输入)、toggle(开关)、select(下拉选择)三种控件类型。
3. 弹窗交互
// 简单提示框
await StremioEnhancedAPI.showAlert("info", "提示", "插件运行成功", ["OK"]);
// 输入框(可取消,取消时返回 null)
const name = await StremioEnhancedAPI.showPrompt("标题", "请输入你的名字", "默认值");
弹窗实现见 src/preload/api/alert.ts,showPrompt 返回 Promise,可直接配合 await 使用。
四、安装与验证:三步确认你的插件跑起来了
写完之后,按下面流程部署(对应设置页截图):
- 进入设置,滚动到底部,点击 OPEN PLUGINS FOLDER 按钮,打开插件目录(各系统路径见 src/core/Properties.ts);
- 把你的
MyFirstPlugin.plugin.js复制进该目录; - 重启 Stremio Enhanced,或按
Ctrl+R刷新页面。
刷新后在 Plugins 分类下就能看到你的插件卡片,显示名称、版本、作者和描述,打开右侧开关即完成加载:
五、发布插件:让别人的 Stremio 也能用上
想分发你的插件,最简单的方式是把文件放到任意可公开访问的静态地址(如代码仓库的 raw 链接),并在元数据中填写 @updateUrl,用户即可一键安装并自动收到更新提示。
Stremio Enhanced 还内置了社区市场(Community 标签页),从注册表拉取社区提交的插件与主题,可一键 Install/Uninstall:
六、新手常见坑位清单
- ❌ 扩展名写错:必须是
.plugin.js,写成.js不会被识别; - ❌ 元数据缺失:
@name、@description、@author、@version四项必填,缺一插件不显示; - ❌ 忘记刷新:新装/修改插件后需重启或
Ctrl+R才能生效; - ❌ 全局变量污染:插件运行在共享页面环境中,建议用闭包(IIFE)包裹你的代码,避免变量泄漏影响其他插件;
- ❌ 依赖不存在的 DOM:Stremio 页面升级后 class 名可能变化,操作前建议先判断元素是否存在。
写在最后
回顾一下完整流程:元数据注释 → 主体脚本 → 放入插件目录 → 刷新启用,这就是写出第一个 .plugin.js 的全部路径。有了内置的日志、配置面板和弹窗 API,你可以继续尝试更复杂的想法——快捷键增强、播放行为定制、界面交互扩展,都可以用同样的模式实现。动手写一个属于自己的插件吧,这就是 Stremio Enhanced 插件开发最有趣的地方。


