插件基础知识
本页介绍插件的加载流程、apiVersion 规则、页面注册与本地化，以及插件读写配置的方式。
加载流程
桌面应用启动时，宿主按以下顺序处理插件：
- 处理卸载标记：带
.uninstall标记的插件目录在本次启动被移除（配置目录保留，见卸载与配置语义）。 - 处理待安装包：
data/cache/plugin-packages下的.srpx包解压到data/plugins/<id>，同 id 包会整目录替换以支持更新。 - 发现插件：扫描
data/plugins下各目录中的manifest.yml，同时并入--epp指定的外部开发目录。 - 校验清单并解析加载顺序：按
dependencies拓扑排序，环或缺失的必需依赖会标记为加载失败。 - 加载：为每个插件创建独立的
PluginLoadContext，从入口程序集查找唯一的非抽象PluginBase实现并调用Initialize。
插件目录
- 已安装插件：
data/plugins/<id> - 待安装包：
data/cache/plugin-packages - 插件私有配置：
data/config/plugins/<id>
apiVersion 与版本
manifest.yml的apiVersion声明插件目标宿主 API，主版本必须不低于宿主PluginApiVersions.Current.Major（当前为3）。不满足时插件会被拒绝加载。详见插件 API 版本与兼容性。apiVersion跟随应用主版本递增；version是插件自身版本，两者相互独立。- 插件包版本（
version）用于市场中的更新判断；宿主安装包时以id为准，同 id 即视为更新。
页面注册与本地化
插件可以注册设置页与主页面：
- 页面 id 遵循
plugin.<id>.*命名空间，并在应用注册表内唯一。 - 通过 Core 扩展注册：
services.AddSettingsPage<T>(title)/services.AddMainPage<T>(title)，并为页面类标注[PageInfo("plugin.<id>.xxx", Icon)]。 - 注册在插件入口
Initialize中进行，发生在宿主 Host 构建之前。
本地化：
- 用户可见字符串按"每页一个文件夹"维护
Resources.resx、Resources.en-US.resx、Resources.ja-JP.resx，简体中文、英文、日文三语齐全。 - 资源设计器使用
PublicResXFileCodeGenerator；项目文件中只注册Resources.resx与Resources.Designer.cs。 - 切换应用语言后宿主会请求重启，重启后插件资源按
CultureInfo.CurrentUICulture自动加载对应语言。插件不应假定固定文化，也不要将页面文本并入宿主共享资源桶。
配置
插件经 DI 注入 MainConfigHandler 读写主配置，或继承 ConfigHandlerBase<T> 管理自己的配置：
public override void Initialize(HostBuilderContext context, IServiceCollection services)
{
services.AddSingleton<MyPluginConfigHandler>();
}- 集合类配置修改不会自动保存，需在变更后调用
Save()。 - 不要直接修改主配置的持久化路径；插件私有文件统一写入
PluginConfigFolder（即data/config/plugins/<id>）。
卸载与配置语义
- 卸载：设置页卸载操作写入
.uninstall标记，下次启动移除插件目录；data/config/plugins/<id>配置目录保留。 - 启用/禁用：设置页开关写入
.disabled标记，重启生效。 - 崩溃自动禁用：全局异常若堆栈归属某插件加载上下文，该插件自动写入
.disabled，下次启动不再加载。
安全边界
插件在宿主进程内运行，不是沙箱：插件代码拥有与宿主相同的进程权限与数据访问能力。市场校验通过 SHA-256 与 Ed25519 签名保证发布物完整性，但进程内插件仍应被视为可信任代码。不要向不受信任来源的插件授予数据或凭据访问权。
贡献者
陈晋瑭更新日志
2026/10/31 00:21
查看所有更新日志
c13ca-于
版权所有
版权归属：SECTL
许可证：CC BY-NC-SA 4.0