跳到主要内容

插件管理

本页面向运维与开发，说明插件的导入、刷新、打开目录、删除与重置等操作流程。

版本说明

本页涉及能力在 3.0.0-dev.4 及之后版本可用。

快速心智模型​

  • 源码包（Source Package）：你编写/分发的插件目录（manifest + Lua 或原生库 + 可选资源）
  • 已安装插件（Installed Plugin）：Core 管理的运行时插件副本
  • 插件数据（Plugin Data）：插件运行产生的配置、缓存、状态数据

Core 负责安装与运行时存储管理。建议将运行时路径视为内部实现，不要依赖目录命名。

导入队列​

有两类导入队列：

队列典型用途导入成功后源码目录
import/plugin/一次性安装/更新自动移除
import/plugin-dev/开发调试迭代保留

推荐流程​

开发流程​

  1. 将插件源码放入 import/plugin-dev/<type>.<id>/
  2. 在 UI 点击“刷新插件”
  3. 在 UI 中测试效果
  4. 持续迭代

这个流程无需每次手工复制包，适合高频调试。

一次性安装/更新流程​

  1. 将插件包放入 import/plugin/<type>.<id>/
  2. 点击“刷新插件”
  3. 验证插件是否可用

适合离线分发或一次性更新场景。

刷新插件会发生什么​

执行刷新后，通常会：

  • 处理导入队列中的插件
  • 重载插件注册信息
  • 刷新插件运行时状态，使更新尽快生效
  • 通知 UI 插件列表发生变化
  • native-c 入口会通过 shadow copy 缓存加载，因此运行中的进程不会锁住原始 DLL/共享库，更新时可以替换原文件

可用于运维的插件元数据​

get_plugins 返回以下运维信息：

  • pluginDir：插件运行时目录
  • dataDir：插件数据目录（若存在）
  • bundled：是否为应用打包插件
  • installSource：bundled | import | import-dev | package | manual

建议使用这些字段做排障/工具集成，而不是猜测插件来源。

打包插件 vs 用户安装插件​

打包插件​

  • 随应用打包
  • 通常应执行“重置”，而不是“删除”
  • 若被用户版本覆盖，可通过重置恢复默认版本

用户安装插件​

  • 可删除
  • 删除时可选是否同时清理数据目录

删除 vs 重置​

删除（Delete）​

用于移除当前安装的用户插件副本：

  • 删除已安装插件副本
  • 可选删除插件数据
  • 对于 import-dev 来源，仅删除安装副本，不删除开发源码包

重置（Reset）​

用于恢复默认打包版本：

  • 移除用户覆盖副本
  • 可选清理插件数据
  • 若存在打包版本，重置后将回退到打包版本

打开目录操作​

可通过插件管理/API 打开：

  • 插件目录（总目录或指定插件）
  • 指定插件的数据目录

适合排障、迁移与检查；不建议在业务逻辑中依赖运行时目录结构。

.skyignore 用法​

导入时支持 .skyignore（语法与 .gitignore 类似），常用于排除临时文件与构建垃圾。

示例：

*.tmp
*.log
build/
node_modules/
!important.log

对于 native-c 源码包，建议排除 target/、bin/、obj/ 等构建目录，并确保已编译产物位于 manifest.json 的 entry 声明路径下。

常见问题​

刷新后看不到插件​

  • 目录命名是否为 <type>.<id>
  • manifest.json 是否合法
  • 是否放在正确导入队列
  • Core 日志是否有 manifest/runtime 报错

删除后插件又出现​

通常是 import/plugin-dev/ 源码包仍在，刷新/重启后会再次导入。

数据目录没有被清理​

仅在 deleteData / resetData 开启时才会清理数据目录。

实际生效版本不符合预期​

刷新插件后查看 installSource、pluginDir 等字段，确认当前激活来源。

相关文档​