发布到插件市场

更新于 2026-09-29在 GitHub 上编辑

工作区里 external/ 下的插件只在开发模式被扫描，不会进入发行包。要让它出现在插件市场、并分发给其他面板，用发布脚本上传。

准备插件信息

市场先读取 panel/plugin.json；只有没有 Panel 端的 Daemon-only 工作区才回退到 daemon/plugin.json。双端插件不要在 Daemon 清单中重复元数据。

字段 用途

id

必填的唯一 slug：2–64 个小写字母、数字、_、-，以字母开头，且不能是 Windows 保留设备名。脚手架默认让它与工作区目录名一致，但发布脚本不要求二者相同。

displayName / name

展示名称。

description

插件简介；列表与详情共用这一字段，不再使用 summary。

category

分类。

changelog

更新日志（也可以用 --changelog 覆盖本次上传）。

此外，工作区根目录可以放一个方形 icon.png：它会随包上传，作为市场卡片与详情页的图标；不放则用市场的默认拼图图标。图标必须是合法 PNG，最大 1 MiB，并只打进市场优先读取的一端。

插件自述

panel/README.md（或 daemon/README.md）是给用户看的自述，随包发布，市场会按 Markdown 渲染在"自述"页签里。写清插件做什么、怎么配置、有什么注意事项。

工作区根目录的 README.md 是开发者说明，不会发布。

绑定市场账号

首次发布会触发账号绑定：脚本生成一个 state，打开市场的 /connect 页面由你在浏览器里登录授权，脚本轮询直到授权完成。

  • 登录完全在浏览器里进行，脚本不接触密码，也没有回调地址；

  • 授权后凭据写入仓库根目录的 data/epanel-market.json；连接按市场地址分别保存，可同时使用多个市场；

  • 默认市场为 https://market.elementspanel.top，可用 --market <url> 指定其他市场；

  • npm run publish-plugin — --disconnect 会撤销当前默认市场的令牌；配合 --market 可断开指定市场。

SECURITY: data/epanel-market.json 里的 token 等同于你的市场账号，不要提交到版本库。

发布

# 发布 hello 工作区
npm run publish-plugin -- hello

# 指定版本与更新日志（只作用于本次上传）
npm run publish-plugin -- hello --version 1.1.0 --changelog "Add shout option"

# 只编译、不上传，用于本地检查产物
npm run publish-plugin -- hello --compile-only

# 指定市场地址
npm run publish-plugin -- hello --market https://market.example.com

# 撤销本机与默认市场的发布授权
npm run publish-plugin -- --disconnect

脚本会：

  1. 用 scripts/compile-plugin.mjs 编译面板与节点两半；

  2. 校验产物（只允许真实插件包会包含的扩展名；PNG 需为合法签名且不超限）；

  3. 写入 elements.api / elements.sdk 兼容元数据并校验产物；

  4. 上传，市场再次校验两端清单与入口，并将版本放入审核队列。

--version 与 --changelog 只写进编译产物里的 plugin.json，工作区清单保持不变。

发布前要先安装好插件自己的 npm 依赖。编译器会把普通 JavaScript 依赖打包，但不会执行 npm install，也不会上传 node_modules、锁文件或 .npmrc。仅含原生扩展或运行时文件的包需要额外的打包支持。

审核与上架

上传不会立即对公众可见 —— 市场把每次上传放进审核队列，通过后才出现在列表与详情页。公开详情接口 GET /api/plugins/:id?version=…​ 返回说明、已通过审核的版本历史、最新版本与所选版本。

安装到面板时，市场文件列表包含每个文件的 SHA-256，面板在写入或分发前校验字节，确保传输内容与市场声明一致。

兼容性

编译会为插件写入兼容元数据：浏览器插件为 elements: { api: 1, sdk: 1 }，仅后端的插件为 elements: { api: 1 }。运行时、安装器与市场都会据此判断兼容性：

  • 运行时与安装器在执行代码前拒绝声明了不支持版本的包；

  • 声明了版本要求的节点插件，还要求目标节点返回匹配的 plugin/capabilities；

  • 缺失元数据的包被当作旧包处理。

不要给手工拼装的、不兼容的包盖上版本戳。校验和只能发现内容不一致，不能认证恶意的市场，也不能让同进程插件彼此隔离。

常见问题

提示包内含市场不接受的扩展名。

编译产物里混进了非插件文件；先在本机看看 --compile-only 的输出，去掉多余文件。

授权页面打不开。

确认 --market 指向的市场可达；未指定时检查 https://market.elementspanel.top。

上传后市场看不到。

通过审核前不会公开显示，属正常；检查脚本最后列出的版本审核状态。

下一步

  • 插件系统 —— 插件从哪里加载、如何被启用。

  • 插件结构 —— 清单字段与上下文服务的完整参考。

© 2026 ElementsPanel