Skip to content

Cross Platform Plugins

Jump to bottom
雪绫 edited this page Aug 25, 2026 · 1 revision

跨平台插件

插件市场以操作系统和 CPU 架构共同决定下载包。规范名称固定为：

系统 Manifest 键 .NET RID
Windows windows win-x64、win-arm64
Linux linux linux-x64、linux-arm64
macOS macos osx-x64、osx-arm64

Manifest 使用 macos，.NET Runtime Identifier 使用 osx，两者不要混用。CPU 键固定为 amd64、arm64、anycpu。

下载 API

一个版本可以声明任意非空系统组。每个组至少包含一个 CPU 包：

{
  "version": "1.4.0",
  "pclCoreVersion": "2026.08.1",
  "downloads": {
    "windows": {
      "amd64": {
        "packageUrl": "https://github.com/example/plugin/releases/download/v1.4.0/example-1.4.0-windows-amd64.pclx",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      },
      "arm64": {
        "packageUrl": "https://github.com/example/plugin/releases/download/v1.4.0/example-1.4.0-windows-arm64.pclx",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    },
    "linux": {
      "amd64": {
        "packageUrl": "https://github.com/example/plugin/releases/download/v1.4.0/example-1.4.0-linux-amd64.pclx",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      },
      "arm64": {
        "packageUrl": "https://github.com/example/plugin/releases/download/v1.4.0/example-1.4.0-linux-arm64.pclx",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    },
    "macos": {
      "amd64": {
        "packageUrl": "https://github.com/example/plugin/releases/download/v1.4.0/example-1.4.0-macos-amd64.pclx",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      },
      "arm64": {
        "packageUrl": "https://github.com/example/plugin/releases/download/v1.4.0/example-1.4.0-macos-arm64.pclx",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    }
  }
}

packageUrl 必须是完整 HTTP/HTTPS .pclx URL，sha256 必须是 64 位十六进制 SHA-256。同一个版本的 GitHub Topic 插件还必须让包地址和 releaseNotes 指向同仓库、同 Release Tag。

选择与兼容规则

客户端先按当前系统选择 windows、linux 或 macos，再在组内选择当前 CPU；精确键不存在时使用该组的 anycpu。系统组存在但 CPU 不匹配时直接判定不兼容，不读取其他系统组，也不读取旧版顶层键。

为兼容已有 Manifest，当前系统组完全不存在时，客户端才读取 downloads 顶层的 amd64、arm64、anycpu。顶层 anycpu 表示包同时不依赖系统和 CPU；系统组内的 anycpu 只表示不依赖 CPU，并不表示跨系统。

未知系统只会尝试旧版顶层键。未知键、空系统组、系统组内未知 CPU、空下载对象都会被服务端拒绝。

项目和原生依赖

插件项目的目标框架必须能够引用目标启动器版本提供的 PCL.Core.dll。当前发布使用的具体 TFM 以对应版本产物为准；不要仅根据本页把项目改成一个启动器尚未提供的目标框架。共享代码应避免直接依赖 Windows 专属 API，并把系统实现拆到平台专用程序集或源码条件中。

不要把 PCL.Core.dll 或 PCL.Mixin.dll 打进 PCLX。原生库应按其 RID 放入对应系统/CPU 包，不能依赖安装后再猜测或替换二进制。平台不支持应在市场选包阶段发现，而不是下载后等到程序集加载失败。

运行时判断应使用 RuntimeInformation.IsOSPlatform(...) 与 RuntimeInformation.OSArchitecture，不要根据路径分隔符、环境变量或系统显示名称推断平台。

发布和测试

推荐资产名包含系统和 CPU，例如：

example-1.4.0-windows-amd64.pclx
example-1.4.0-linux-arm64.pclx
example-1.4.0-macos-arm64.pclx

含平台代码或原生依赖的插件至少应覆盖 Windows、Linux、macOS 的 AMD64 和 ARM64 六个组合。每个组合都要验证选包、SHA-256、安装、启动、更新回滚和不兼容提示；组内 anycpu 还要在两种 CPU 上各测一次。没有对应设备时可以使用 CI runner 或虚拟机，但发布前仍应保留真实系统的启动验证。

Clone this wiki locally