Skip to content

Build Pack Install

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

构建、打包与安装

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

准备工作

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

构建 C# 插件

在插件项目目录运行：

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

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

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

构建 JavaScript 插件

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

plugin.json
main.js
lib/
resources/

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

SDK 包来源

C# 插件引用 NuGet.org 上的 SDK 包：

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

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

插件发布包

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

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

解压后应能直接放到：

PCL/Plugins/com.example.myplugin/

发布包根目录应直接包含 plugin.json，不要再套一层无意义的外层目录。用户解压后能看到类似下面的结构即可：

plugin.json
MyPlugin.dll
DependencyA.dll
Resources/

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

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。

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

安装后检查

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

  • 插件目录中存在 plugin.json。
  • entry 指向的 DLL 或 JS 文件真实存在。
  • C# 插件目录中没有 PCL.Plugin.Abstractions.dll。
  • minApiVersion 没有高于当前启动器提供的插件 API 版本。
  • 需要 UI、CLI、URI 或扩展点能力时，capabilities 已声明对应能力。
  • 启动器日志中没有插件加载异常。

本地开发建议

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

$pluginDir = "$env:APPDATA\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 数据目录可能因启动器配置而不同，请以你的测试环境为准。

版本发布建议

  • 插件版本使用四段式版本号或 SemVer 兼容格式。
  • 修改 SDK 能力需求时同步提高 minApiVersion。
  • 发布包中附带 changelog。
  • 对破坏性变更提高主版本。

发布检查清单

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

Clone this wiki locally