# 18. 如何限定插件可安装的 MoviePilot 主系统版本？

如果插件依赖某个 MoviePilot 主程序版本才提供的后端接口、前端能力、事件字段或运行时模块，应在对应的 `package.json` / `package.v2.json` 条目中增加 `system_version` 字段。

```json
{
  "MyPlugin": {
    "name": "我的插件",
    "version": "1.0.0",
    "system_version": ">=2.12.0"
  }
}
```

字段规则：

- `system_version` 的格式参考 pip 依赖版本范围，也就是 PEP 440 specifier，例如 `">=2.12.0"`、`">=2.12.0,<3"`、`"~=2.12"`。
- MoviePilot 当前版本号带 `v` 前缀也可以正常比较，因此 `>=v2.12.0` 和 `>=2.12.0` 都能解析；文档和索引中推荐写不带 `v` 的形式。
- 未定义 `system_version` 时，宿主不做主系统版本检查，保持旧插件兼容。
- 如果当前主系统版本不满足范围，插件市场会显示不兼容提示，安装和更新都会被拒绝。

发布插件时，建议在以下场景补充该字段：

- 插件调用了新版本才存在的后端 API、helper、chain、module 或事件字段。
- 插件的 Vue 远程组件依赖新版本前端才支持的加载、侧栏、仪表板或渲染行为。
- 插件换用了新版本 MoviePilot 才内置或才稳定可用的系统能力，例如浏览器运行时、统一缓存、智能体工具注册等。
