Skip to content

Troubleshooting

Jump to bottom
MuXue1230 edited this page Jul 14, 2026 · 4 revisions

故障排查

SDK 0.1.0-alpha.4

NuGet 找不到包

确认包 ID 使用 PCLN.Plugin.*，不是旧的 PCL.N.Plugin.*：

dotnet nuget list source
dotnet add package PCLN.Plugin.Abstractions --version 0.1.0-alpha.4 --source https://api.nuget.org/v3/index.json

清理失败缓存：

dotnet nuget locals all --clear
dotnet restore

没有生成 .pnp

检查：

  • 已引用 PCLN.Plugin.Sdk.Build；
  • <PclNPluginBuildEnabled>true</PclNPluginBuildEnabled>；
  • 已设置 PclNPluginId；
  • plugin.json 存在于 PclNPluginManifest 指向的位置；
  • 运行的是真正 Build，不是仅设计时构建。

PNPBUILD005

缺少 PclNPluginId：

<PclNPluginId>dev.example.plugin</PclNPluginId>

它必须与 Manifest id 一致。

PNPBUILD006

通用包不是 AnyCPU。纯托管插件使用：

<PlatformTarget>AnyCPU</PlatformTarget>

架构专用包则设置 PclNPluginRuntimeIdentifier。

AXAML 未进入包

  • Manifest 使用 ui/...axaml；
  • 路径只用 /，不含 .. 或反斜杠；
  • 文件实际存在于 PclNPluginContentRoot 下；
  • 不含 x:Class 或私有宿主 CLR 命名空间。

GPG 签名失败

gpg --version
gpg --list-secret-keys --with-subkey-fingerprint

确认：

  • gpg 可执行；
  • Manifest 使用完整主密钥指纹；
  • 私钥/签名子密钥存在且未过期、未吊销；
  • CI 已导入私钥并能非交互使用；
  • 没有把短 Key ID 当作指纹。

插件安装失败

按顺序检查：

  1. ZIP 路径和文件表是否安全；
  2. 每个文件 SHA-256 是否匹配；
  3. OpenPGP 签名与 Manifest 指纹是否匹配；
  4. entryPoint.assembly 是否存在；
  5. API/Host/服务版本范围是否兼容；
  6. required 前置是否安装且启用；
  7. 是否误带共享或私有宿主程序集。

插件显示“缺少前置”

打开“设置 → 插件 → 已安装”查看缺少的 ID 和版本范围。先安装并启用 required 前置，再启用当前插件。检查依赖图是否出现环。

插件能安装但无法启用

  • required 服务不可用；
  • Manifest 不兼容另一已启用插件；
  • Plugin Safe Mode 已开启；
  • 未签名插件没有开发者模式授权；
  • InitializeAsync 抛出异常；
  • 入口类型不符合要求。

UI 没有出现

  • Surface ID、版本范围或 Slot 不匹配；
  • access 和权限缺失；
  • UI Safe Mode 跳过高风险 Patch；
  • AXAML 安全验证失败；
  • Patch 与其他插件冲突；
  • fallback 让可选功能被禁用。

在开发者模式中显示“UI Patch”和“兼容性”页面查看计划与冲突。

PNPSDK005

保存注册结果并调用：

context.Lifetime.Track(registration);

插件停用后仍占用文件

通常表示插件保留了静态引用、事件订阅、后台线程或未释放资源：

  • 避免静态保存宿主服务或插件实例；
  • 所有注册交给 Lifetime；
  • 后台工作使用 IPluginTaskService；
  • 取消后等待任务结束；
  • 释放流、Watcher、Timer 和原生句柄。

Clone this wiki locally