如何在 Ulanzi Studio 快速发布你的插件

chxdon · 发表于昨天 22:08

把插件做完以后，最后一步就是把 .ulanziPlugin 插件包、封面图和展示图上传到 Ulanzi Studio。本文用一个从拖拽上传到解析成功的流程，带你快速检查 manifest.json、准备图片资源，并完成发布前的自动校验。

拖拽插件到上传页面并解析成功

一、发布前先准备 3 类资源
发布页面的第一步是上传资源。你至少需要准备：

资源	是否必需	要求
主插件文件	必需	压缩包，上传页提示单文件最大 50MB
Cover image 封面图	必需	比例 2:1，用于 Marketplace 封面
Banner 01	必需	比例 3:2，用于详情页轮播和推荐位
Banner 02 / Banner 03	可选	比例 3:2，建议补充配置界面、设备使用场景或核心功能状态

拖拽主插件文件后，Ulanzi Studio 会解析插件包里的 manifest.json。解析成功后，再上传封面和 Banner，并填写名称、概要和详细介绍等上架信息。

二、插件包结构建议
一个发布友好的插件包通常长这样：

com.ulanzi.example.ulanziPlugin/
├── manifest.json
├── plugin/
│ ├── app.html 或 app.js
│ └── actions/
├── property-inspector/
│ └── action/inspector.html
├── assets/
│ ├── icons/
│ ├── actions/
│ └── banners/
├── en.json
└── zh_CN.json

复制代码

文件夹命名建议使用 com.ulanzi.{插件名}.ulanziPlugin。插件主服务 UUID 建议保持 4 段，例如 com.ulanzi.ulanzistudio.example；Action UUID 需要以主服务 UUID 为前缀，并多于 4 段，例如 com.ulanzi.ulanzistudio.example.toggle。

三、manifest.json 字段说明
manifest.json 是上传解析的核心。发布前先确认这些字段完整、路径正确、资源真实存在。

1. 顶层字段

字段	是否必需	说明
Author	必需	开发者或组织名称
Name	必需	插件名称，会显示在插件列表或市场页面
Overview	推荐，新增	简短概要，用于市场列表、卡片或摘要展示；建议一句话说明插件价值
Description	必需	插件详细描述，可写功能、配置步骤、使用注意事项
Icon	必需	插件图标路径，相对插件根目录
Version	必需	插件版本号，例如 1.0.0
Category	推荐	插件分类名称
CategoryIcon	推荐	分类图标路径
Banner	推荐，新增	Banner 图片路径数组，第一张为主 Banner
UUID	必需	插件主服务 UUID，建议 4 段
Type	必需	固定为 JavaScript
CodePath	必需	插件主入口，支持 .html 或 .js
Actions	必需	插件提供的功能列表
OS	推荐	支持的平台和最低系统版本
Software.MinVersion	推荐	最低 Ulanzi Studio 版本；新字段使用 MinVersion，不要再用旧的 MinimumVersion
ApplicationsToMonitor	可选	需要监听启动/退出的外部应用
Inspect	可选	Node 插件远程调试参数，例如 --inspect=127.0.0.1:9201
PrivateAPI	可选	仅在插件确实使用私有接口时配置
Profiles	可选	随插件安装的预设配置
InstallToDepsApp	可选	需要安装到第三方应用的脚本配置

新增的两个发布字段建议这样写：

{
"Overview": "Control OBS recording, scenes, and streaming from your Ulanzi device.",
"Banner": [
"assets/banners/banner-1.png",
"assets/banners/banner-2.png",
"assets/banners/banner-3.png"
]
}

复制代码

Overview 要短，适合列表页快速扫读；Banner 是插件包内的相对路径数组，第一张会作为主展示图优先使用。上传页也会要求单独上传 Cover image 和至少一张 Banner，建议保持包内 Banner 与上传素材风格一致。

2. Action 字段
每个 Action 至少要有名称、图标、UUID 和状态图：

字段	是否必需	说明
Name	必需	功能名称
Icon	必需	Action 图标路径
UUID	必需	Action UUID，必须以前面的插件主 UUID 为前缀
PropertyInspectorPath	可选	配置界面 HTML 路径
state	可选	默认状态索引
States	必需	状态列表，每个状态包含 Name 和 Image
Tooltip	推荐	功能提示
SupportedInMultiActions	可选	是否支持多项操作
DisableAutomaticStates	可选	设为 true 表示由插件自己控制状态切换
Controllers	推荐	支持 Keypad、Encoder，未设置时通常按 Keypad 处理
Encoder	Encoder 必需	旋钮布局，例如 { "layout": "$UA1" }
Devices	可选	指定设备型号，如 D200、D200H、Dial、D200X；"~Dial" 表示排除 Dial

示例：

{
"Name": "Start Recording",
"Icon": "assets/actions/record/icon.png",
"PropertyInspectorPath": "property-inspector/record/index.html",
"state": 0,
"States": [
{
"Name": "Stopped",
"Image": "assets/actions/record/off.png"
},
{
"Name": "Recording",
"Image": "assets/actions/record/on.png"
}
],
"Tooltip": "Start or stop recording",
"UUID": "com.ulanzi.ulanzistudio.obs.record",
"SupportedInMultiActions": false,
"DisableAutomaticStates": true,
"Controllers": ["Keypad", "Encoder"],
"Encoder": {
"layout": "$UA1"
},
"Devices": ["D200X", "~Dial"]
}

复制代码

四、Icon 和封面资源格式要求
1. 插件内 Icon
manifest.json 里的 Icon、CategoryIcon、Action Icon、States[].Image 都要使用相对插件根目录的路径。

推荐要求：

- 尺寸：196 × 196 px
- 格式：优先 PNG
- 背景：根据图标设计选择透明或实底，但小尺寸下要清晰
- 内容：居中、高对比、少文字；除非文字就是功能本身，否则不要放很小的字

协议中插件图标资源支持 svg、png、jpg，但为了设备显示和自动校验更稳定，发布插件时建议统一输出 196 × 196 的 PNG 图标。

2. Cover image 封面图
上传页要求 Cover image 使用 2:1 比例。建议：

- 比例：2:1
- 格式：PNG 或 JPG
- 内容：突出插件名称、核心功能和品牌识别
- 构图：避免把关键信息贴近边缘，因为上传页可能会裁剪

3. Banner 展示图
上传页要求 Banner 使用 3:2 比例，并且至少上传 Banner 01。建议：

- 比例：3:2
- 数量：至少 1 张，最多按上传页准备 3 张
- Banner 01：突出插件图标、插件名称和一句核心价值
- Banner 02/03：展示真实设备使用、配置界面、功能状态或典型工作流
- 格式：PNG 或 JPG

如果插件包内也配置了 Banner 字段，建议把图片放在 assets/banners/ 下，并保持和上传页素材一致：

{
"Banner": [
"assets/banners/banner-1.png",
"assets/banners/banner-2.png"
]
}

复制代码

五、一个完整 manifest 示例

{
"Author": "Ulanzi",
"Name": "OBS Controller",
"Overview": "Control OBS recording and scene switching from your Ulanzi device.",
"Description": "Connect OBS WebSocket, switch scenes, start or stop recording, and show live recording state on the device.",
"Icon": "assets/icons/plugin.png",
"Version": "1.0.0",
"Category": "Streaming",
"CategoryIcon": "assets/icons/category.png",
"Banner": [
"assets/banners/banner-1.png",
"assets/banners/banner-2.png"
],
"UUID": "com.ulanzi.ulanzistudio.obs",
"Type": "JavaScript",
"CodePath": "plugin/app.js",
"Software": {
"MinVersion": "3.0.0"
},
"Actions": [
{
"Name": "Record",
"Icon": "assets/actions/record/icon.png",
"PropertyInspectorPath": "property-inspector/record/index.html",
"state": 0,
"States": [
{
"Name": "Stopped",
"Image": "assets/actions/record/off.png"
},
{
"Name": "Recording",
"Image": "assets/actions/record/on.png"
}
],
"Tooltip": "Start or stop OBS recording",
"UUID": "com.ulanzi.ulanzistudio.obs.record",
"SupportedInMultiActions": false,
"DisableAutomaticStates": true,
"Controllers": ["Keypad"]
}
]
}

复制代码

六、上传发布流程
1. 打包插件文件夹，确保压缩包内包含 manifest.json、入口文件、图标、配置页和语言文件。
2. 打开 Ulanzi Studio 的上传页面，进入 Upload works。
3. 在 Main work file 区域拖拽或点击上传插件压缩包。
4. 等待自动解析。解析成功后，检查插件名称、版本、入口和 Action 信息是否符合预期。
5. 上传 2:1 的 Cover image。
6. 上传至少 1 张 3:2 的 Banner，建议补齐 2-3 张。
7. 填写名称、概要和详细介绍；如果需要多语言展示，同步填写对应语言版本，并在插件包内提供语言 JSON。
8. 确认右侧 Auto check 全部通过后，点击上传。

七、发布前检查清单
- manifest.json 是合法 JSON，没有注释和多余逗号。
- CodePath 指向真实存在的 .html 或 .js 文件。
- 主 UUID 是 4 段，Action UUID 以前缀继承并多于 4 段。
- Overview 已填写一句话概要。
- Banner 路径数组存在，且图片文件真实存在。
- Software.MinVersion 使用新字段，不再使用废弃的 Software.MinimumVersion。
- 所有 Icon、Action Icon、State Image 路径都能在插件包里找到。
- 插件内图标建议为 196 × 196 PNG。
- Cover image 是 2:1。
- Banner image 是 3:2，至少准备 Banner 01。
- Node 插件如果使用 dist/，上传前已经重新构建。
- Property Inspector 页面背景设置为透明。

最后，用上传页自动解析来做一次真实检查。只要主文件解析成功、封面和 Banner 都符合比例要求，后续填写上架信息就会顺得多。

		自动登录	找回密码
密码			立即注册