Skip to content

Build Pack Install

Jump to bottom
雪绫 edited this page Aug 25, 2026 · 5 revisions

构建、打包与安装

一个完整发布包含三部分：插件程序集、PCLX 包和用于商店/更新的 manifest.json。

构建项目

插件应引用目标启动器版本的 PCL.Core.dll。官方 Release 只发布单文件 apphost；请先按照 快速开始 中的步骤从目标版本 EXE 提取 DLL，并确认输出的 BaseVersion 与 Release Tag 一致。本地构建启动器时也可以直接使用同次构建的 PCL.Core/bin/<配置>-<架构>/net8.0-windows/PCL.Core.dll。

然后构建插件：

dotnet build .\Example.Plugin.csproj `
  -c Release `
  -p:PclCorePath=C:\PCL-Nex\PCL.Core.dll

项目引用必须使用 Private=false，确保输出目录和 PCLX 中不会复制 PCL.Core.dll。

发布前记录该 DLL 对应的 BaseVersion，并把同一个值写进：

  • PCLX 内 plugin.json.pclCoreVersion。
  • 发布 manifest.json 对应版本的 pclCoreVersion。

组装 staging 目录

artifacts/stage/
  plugin.json
  README.md
  lib/
    Example.Plugin.dll
    Example.Plugin.pdb
  mixins/
    example.plugin.mixins.json
  assets/
    logo.png

一个简单的 PowerShell 打包流程：

$ErrorActionPreference = 'Stop'
$root = $PSScriptRoot
$stage = Join-Path $root 'artifacts\stage'
$artifact = Join-Path $root 'artifacts\example.plugin-1.0.0-anycpu.pclx'
$zip = [System.IO.Path]::ChangeExtension($artifact, '.zip')

dotnet build (Join-Path $root 'Example.Plugin.csproj') `
  -c Release `
  -p:PclCorePath=$PclCorePath
if ($LASTEXITCODE -ne 0) { throw 'dotnet build failed' }

if (Test-Path -LiteralPath $stage) {
  Remove-Item -LiteralPath $stage -Recurse -Force
}

New-Item -ItemType Directory -Force `
  -Path (Join-Path $stage 'lib'), (Join-Path $stage 'mixins') | Out-Null

Copy-Item (Join-Path $root 'package\plugin.json') $stage
Copy-Item (Join-Path $root 'package\example.plugin.mixins.json') `
  (Join-Path $stage 'mixins\example.plugin.mixins.json')
Copy-Item (Join-Path $root 'bin\Release\net8.0-windows\Example.Plugin.dll') `
  (Join-Path $stage 'lib\Example.Plugin.dll')

if (Test-Path -LiteralPath $artifact) { Remove-Item $artifact -Force }
if (Test-Path -LiteralPath $zip) { Remove-Item $zip -Force }
Compress-Archive -Path (Join-Path $stage '*') -DestinationPath $zip
Move-Item -LiteralPath $zip -Destination $artifact

Get-FileHash -LiteralPath $artifact -Algorithm SHA256

如果你的项目输出 PDB，建议测试包携带 PDB，方便异常堆栈和目标诊断。正式发布是否携带由作者决定。

检查包内容

发布前确认：

  • plugin.json 在 ZIP 根目录。
  • entryAssembly 指向存在的 DLL。
  • mixinConfig / mixinConfigs 的每个文件都存在。
  • Mixin 配置中的 package 和 mixins 能组合成真实类型名。
  • 包内没有 PCL.Core.dll 或 PCL.Mixin.dll。
  • 包内路径没有 ..、绝对路径或驱动器路径。
  • plugin.json 与市场 Manifest 的 ID、版本、Core 版本和依赖一致。

生成 SHA-256

(Get-FileHash .\artifacts\example.plugin-1.0.0-anycpu.pclx -Algorithm SHA256).Hash

把完整 64 位结果写进对应系统和架构的 downloads：

{
  "linux": {
    "arm64": {
      "packageUrl": "https://github.com/example/example-plugin/releases/download/v1.0.0/example.plugin-1.0.0-linux-arm64.pclx",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

GitHub Release

GitHub 仓库发布流程：

  1. 创建 1.0.0 或 v1.0.0 Tag。
  2. 创建同 Tag 的 GitHub Release。
  3. 上传一个或多个 .pclx 资产。
  4. 在仓库根目录更新 manifest.json。
  5. 确认 releaseNotes 和所有 packageUrl 指向同一 Tag。
  6. 为仓库添加 pclnexplugin Topic。

Manifest 中的 URL 必须是完整地址，客户端不会根据资产名称猜测下载地址。

平台包

如果插件及其依赖完全不区分操作系统和 CPU，可以保留旧版顶层 anycpu。只是不区分 CPU、但使用了系统 API 的包，应放在对应系统组的 anycpu。包含原生库或特定架构组件时分别发布，例如：

example.plugin-1.0.0-windows-amd64.pclx
example.plugin-1.0.0-linux-arm64.pclx
example.plugin-1.0.0-macos-arm64.pclx

不要把 x64 原生文件放进 anycpu 包，也不要把某一系统的原生库放进旧版顶层 anycpu。系统组、RID 和完整发布矩阵见跨平台插件。

本地安装

支持：

  • 在插件页面选择 .pclx。
  • 双击已关联的 .pclx 文件。
  • 使用 pcl://install-plugin URI。
  • 在启动器关闭时，把 staging 目录复制到 PCL/Plugins/<plugin-id>/ 进行 Debug 测试。

直接复制目录只适合本地开发，它不会经过完整下载、SHA-256 和来源记录流程。

更新测试

至少验证：

  • 从已安装版本成功更新。
  • 错误 SHA-256 被拒绝。
  • 新包安装失败时已安装版本仍可用。
  • Manifest 顶层依赖和版本覆盖依赖都能匹配包内 plugin.json。
  • Windows、Linux、macOS 上的 AMD64、ARM64 和组内 AnyCPU 选择符合预期。
  • 修改插件启用状态后重启能正确加载或跳过。

当前不支持在同一进程中替换已加载 DLL 或撤销第三方插件。安装、更新、启用和禁用后应重启启动器。

Clone this wiki locally