如何在 Ulanzi Studio 快速发布你的插件
把插件做完以后，最后一步就是把 .ulanziPlugin 插件包、封面图和展示图上传到 UGC。本文用一个从拖拽上传到解析成功的流程，带你快速检查 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 处理
EncoderEncoder 必需旋钮布局，例如 { "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. 打开 ugc.ulanzistudio.com 的上传页面，进入 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 都符合比例要求，后续填写上架信息就会顺得多。
页:
[1]