Skip to content

URI Scheme

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

URI Scheme

PCL Nex 会在当前用户注册 pcl:// 和 pclnex:// URI Scheme，并关联 .pclx 插件包文件。外部程序、浏览器链接或本地文件可以通过这些入口唤起启动器并执行受支持的动作。

支持范围

类型 示例 说明
URI Scheme pcl://launch?instance=1.20.1 从浏览器、系统链接或命令行唤起启动器
备用 Scheme pclnex://actions?type=install-plugin&source=https%3A%2F%2Fexample.com%2Fplugin.pclx 与 pcl:// 等价，便于区分 PCL Nex
插件包关联 example.pclx 双击 .pclx 文件时进入插件安装流程

协议与文件关联在启动器启动时自动注册。若系统关联失效，可在启动器设置中使用“修复 URI 与插件包关联”。

URI 解析规则

PCL Nex 支持两种写法。

第一种是以 actions 作为统一入口：

pcl://actions?type=<action>&data=<value>
pcl://actions/<action>/<arg1>/<arg2>

第二种是直接把动作名作为 host：

pcl://<action>?key=value
pcl://<action>/<arg1>/<arg2>

查询参数会进行 URL 解码，+ 会被当作空格。路径参数也会被 URL 解码。

常见参数别名：

含义 参数名
动作名 type、event、action、name
数据 data、arg、args、parameter、value

内置动作

启动游戏

动作名：launch、launch-game、play

pcl://launch?instance=1.20.1
pcl://launch?instance=1.20.1&server=play.example.net

支持参数：

参数 说明
instance / version / name 要启动的实例名称
server / serverIp / ip / address 进入游戏后连接的服务器地址
world / worldName 进入游戏后打开的世界名称

启动并加入服务器

动作名：launch-server、join-server、join

pcl://join?instance=1.20.1&server=play.example.net

该动作要求提供 server 参数，否则会提示缺少服务器地址。

下载原版 Minecraft

动作名：download-vanilla、download-minecraft、install-vanilla、install-minecraft

pcl://download-vanilla?version=1.21.7
pcl://download-vanilla/1.21.7

支持参数：

参数 说明
version / id / name Minecraft 版本号
jsonUrl / json / manifest 可选，版本 JSON 地址
force / overwrite 为 1、true 或 yes 时忽略已有下载检查

安装整合包

动作名：install-modpack、download-modpack、modpack

pcl://install-modpack?url=https%3A%2F%2Fexample.com%2Fpack.zip&name=MyPack
pcl://install-modpack?file=C%3A%5CPacks%5Cpack.zip

支持参数：

参数 说明
file / path 本地整合包文件路径
url / source 远程整合包下载地址，只支持 HTTP/HTTPS
name / instance / instanceName 安装后的实例名称
logo 可选，实例图标
resourceId / projectId 可选，来源资源 ID

安装插件

动作名：install-plugin、plugin-install

pcl://install-plugin?source=https%3A%2F%2Fexample.com%2Fplugin.pclx
pcl://install-plugin?source=https%3A%2F%2Fexample.com%2Fmanifest.json
pcl://install-plugin?file=C%3A%5CPlugins%5Cexample.pclx

支持参数：

参数 说明
source / url / git / file / path 插件来源

插件来源可以是本地 .pclx / .zip 文件、远程 .pclx / .zip 包，或远程插件 manifest。安装前启动器会展示确认提示。

插件自定义 URI 动作

插件可以注册自己的 URI 动作。插件必须在 plugin.json 中声明 RegisterUriAction 能力，否则 context.Host.UriActions 会返回 null。

{
  "capabilities": ["RegisterUriAction"]
}

C# 插件注册示例：

private IDisposable? _uriRegistration;

public override Task LoadAsync(IPluginContext context, CancellationToken cancellationToken = default)
{
    _uriRegistration = context.Host.UriActions?.RegisterAction(new UriActionDescriptor
    {
        Name = "open-room",
        Description = "Open a lobby room from URI.",
        Usage = "pcl://plugin?plugin=com.example.lobby&action=open-room&room=1234",
        Handler = uriContext =>
        {
            var room = uriContext.GetQueryValue("room");
            context.Host.Core.Hint($"Open room: {room}", PluginHintType.Info);
        }
    });

    return Task.CompletedTask;
}

public override Task UnloadAsync(CancellationToken cancellationToken = default)
{
    _uriRegistration?.Dispose();
    return Task.CompletedTask;
}

触发插件动作有两种常用格式：

pcl://plugin?plugin=com.example.lobby&action=open-room&room=1234
pcl://plugin/com.example.lobby/open-room/1234

其中：

参数 说明
plugin / pluginId / id 插件 ID
action / name 插件注册的动作名
其他查询参数 会进入 PluginUriActionContext.Query
路径剩余片段 会进入 PluginUriActionContext.Arguments

命令行等价形式

启动器接收到 URI 参数时，会转换为内部 uri 子命令：

Plain Craft Launcher 2.exe "pcl://launch?instance=1.20.1"

也可以直接使用内部参数形式：

Plain Craft Launcher 2.exe uri --action install-plugin --file C:\Plugins\example.pclx
Plain Craft Launcher 2.exe uri --uri "pcl://install-plugin?source=https%3A%2F%2Fexample.com%2Fplugin.pclx"

.pclx 文件路径会被识别为插件安装动作：

Plain Craft Launcher 2.exe C:\Plugins\example.pclx

安全建议

  • 不要从不可信网页或聊天消息中直接打开安装插件链接。
  • 插件会在启动器内运行代码，安装前应确认来源、作者和发布页。
  • 对外发布 URI 时，所有参数都应 URL 编码，尤其是路径、空格、&、#、? 等字符。
  • 插件自定义动作应只执行可预期、可撤销或需要用户确认的操作。
  • 处理外部 URI 时不要信任参数内容；文件路径、URL、房间号等都应再次校验。

Clone this wiki locally