Stremio Enhanced 插件开发入门:如何写出你的第一个 .plugin.js

原创2026-10-25 09:00:211,648 阅读

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 插件可以在播放动漫时自动弹出"跳过片头"提示:

Stremio Enhanced 插件功能示例: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 使用。

四、安装与验证:三步确认你的插件跑起来了

写完之后,按下面流程部署(对应设置页截图):

  1. 进入设置,滚动到底部,点击 OPEN PLUGINS FOLDER 按钮,打开插件目录(各系统路径见 src/core/Properties.ts);
  2. 把你的 MyFirstPlugin.plugin.js 复制进该目录;
  3. 重启 Stremio Enhanced,或按 Ctrl + R 刷新页面。

刷新后在 Plugins 分类下就能看到你的插件卡片,显示名称、版本、作者和描述,打开右侧开关即完成加载:

Stremio Enhanced 插件安装后的设置界面,显示插件卡片与启用开关

五、发布插件:让别人的 Stremio 也能用上

想分发你的插件,最简单的方式是把文件放到任意可公开访问的静态地址(如代码仓库的 raw 链接),并在元数据中填写 @updateUrl,用户即可一键安装并自动收到更新提示。

Stremio Enhanced 还内置了社区市场(Community 标签页),从注册表拉取社区提交的插件与主题,可一键 Install/Uninstall:

Stremio Enhanced 社区插件市场界面,列出可安装的社区插件与主题

六、新手常见坑位清单

  • ❌ 扩展名写错:必须是 .plugin.js,写成 .js 不会被识别;
  • ❌ 元数据缺失:@name、@description、@author、@version 四项必填,缺一插件不显示;
  • ❌ 忘记刷新:新装/修改插件后需重启或 Ctrl + R 才能生效;
  • ❌ 全局变量污染:插件运行在共享页面环境中,建议用闭包(IIFE)包裹你的代码,避免变量泄漏影响其他插件;
  • ❌ 依赖不存在的 DOM:Stremio 页面升级后 class 名可能变化,操作前建议先判断元素是否存在。

写在最后

回顾一下完整流程:元数据注释 → 主体脚本 → 放入插件目录 → 刷新启用,这就是写出第一个 .plugin.js 的全部路径。有了内置的日志、配置面板和弹窗 API,你可以继续尝试更复杂的想法——快捷键增强、播放行为定制、界面交互扩展,都可以用同样的模式实现。动手写一个属于自己的插件吧,这就是 Stremio Enhanced 插件开发最有趣的地方。

登录后查看全文
stremio-enhanced