Skip to content

Build Pack Install

Jump to bottom
Ling edited this page Jul 12, 2026 · 5 revisions

构建、打包与安装

本页说明如何构建插件、组织发布包并安装到 PCL Nex。

准备工作

  • 使用 .NET 8 SDK 构建 C# 插件。
  • C# 插件项目应引用 PlainCraftLauncher.Plugin.Abstractions 1.2.1，并设置 ExcludeAssets="runtime"。
  • 发布前确认 plugin.json 中的 id、version、runtime、entryAssembly 或 entryScript、minApiVersion 和 capabilities 与实际代码一致。
  • C# 插件还要确认入口类上的 [Plugin] 与 plugin.json 保持一致。
  • 如果插件提供 UI 页面，建议在开发版或单独测试目录中验证，不要直接覆盖日常使用环境。

构建 C# 插件

在插件项目目录运行：

dotnet build .\MyPlugin.csproj --configuration Release --property:Platform=AnyCPU

如果项目使用 WPF 或 Windows 目标框架，在非 Windows 环境构建时可能需要：

dotnet build .\MyPlugin.csproj --configuration Release --property:EnableWindowsTargeting=true

构建产物通常位于：

bin/Release/net8.0-windows/MyPlugin.dll

构建 JavaScript 插件

JS 插件通常不需要编译。发布时复制：

plugin.json
main.js
lib/
resources/

如果你使用自己的打包器，请确保最终入口脚本仍能被 plugin.json 的 entryScript 找到。

SDK 包来源

C# 插件引用 SDK 包：

<PackageReference Include="PlainCraftLauncher.Plugin.Abstractions" Version="1.2.1" ExcludeAssets="runtime" />

包地址：https://www.nuget.org/packages/PlainCraftLauncher.Plugin.Abstractions/

插件发布包

推荐每个插件发布为一个 zip 或 .pclx：

com.example.myplugin.pclx
  plugin.json
  MyPlugin.dll
  DependencyA.dll
  Resources/
    icon.png

发布包根目录应直接包含 plugin.json。本地安装器会在 zip 中查找 plugin.json，但最清晰的结构仍是包根目录直接放置清单和入口文件。

如果插件需要说明文件、许可证或更新日志，可以同时放入：

README.md
LICENSE.txt
CHANGELOG.md

不要包含 SDK DLL

C# 插件发布包不应包含：

PCL.Plugin.Abstractions.dll

原因：宿主和插件必须共享同一个 SDK 契约程序集。如果插件目录里带了自己的副本，CLR 可能把接口视为不同类型，导致宿主无法识别插件入口或注册对象。

手动安装插件

安装结构：

PCL/Plugins/<plugin-id>/
  plugin.json
  入口 DLL 或 main.js
  其他依赖文件

示例：

PCL/Plugins/com.example.hello/
  plugin.json
  HelloPlugin.dll

安装后重启 PCL Nex。插件加载器会扫描 PCL/Plugins/*/plugin.json。PCL/Plugins/*.dll 的旧平铺 DLL 布局仍被兼容，但新插件应使用带 plugin.json 的目录结构。

不同启动器版本或便携配置可能使用不同数据目录。当前默认插件根目录位于启动器数据目录下的 PCL/Plugins。找不到插件目录时，可以先在启动器设置或日志中确认当前数据目录，再在该目录下创建 Plugins 文件夹。

安装后检查

安装或更新插件后建议检查：

  • 插件目录中存在 plugin.json。
  • runtime 为 dotnet 时，entryAssembly 指向的 DLL 真实存在。
  • runtime 为 javascript-v8 时，entryScript 指向的 JS 文件真实存在。
  • C# 插件目录中没有 PCL.Plugin.Abstractions.dll。
  • C# 插件 DLL 内存在 public、带 [Plugin]、实现 IPclPlugin 的入口类型。
  • minApiVersion 没有高于当前启动器提供的插件 API 版本。
  • 需要 UI、URI 或扩展点能力时，capabilities 已声明对应能力。
  • 启动器日志中没有插件加载异常。

本地开发建议

开发时可以用脚本把构建输出复制到插件目录：

$pluginDir = "C:\Path\To\PCL\Plugins\com.example.hello"
New-Item -ItemType Directory -Force $pluginDir | Out-Null
Copy-Item .\plugin.json $pluginDir -Force
Copy-Item .\bin\Release\net8.0-windows\HelloPlugin.dll $pluginDir -Force

实际 PCL 数据目录可能因启动器配置而不同，请以你的测试环境为准。

版本发布建议

  • 插件版本使用能被 System.Version 解析的格式，例如 1.0.0.0 或 1.2.3。
  • 修改 SDK 能力需求时同步提高 minApiVersion。
  • 发布包中附带 changelog。
  • 对破坏性变更提高主版本。

发布检查清单

  • Release 附件只上传最终 zip 或 .pclx，不上传中间构建目录。
  • zip 内没有 bin/、obj/、.pdb 等开发产物，除非你明确希望提供符号文件。
  • 依赖 DLL 只包含插件运行必须的第三方依赖。
  • README 写清楚安装位置、最低启动器版本、最低 API 版本和主要能力。
  • 更新说明列出新增、修复、破坏性变更和已知问题。
  • 如果插件需要网络、文件系统或外部进程，说明用途和关闭方式。

Clone this wiki locally