快速开始（插件）

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

本页用脚手架创建并跑通第一个 ElementsPanel 插件。全程不需要改动 panel/ 或 daemon/ 下的内置插件目录。

前置条件

  • 已克隆 ElementsPanel 源码并安装全部工作区依赖：Linux/macOS 执行 ./install-dependents.sh，Windows 执行 install-dependents.bat。

  • 只做插件开发时，不需要理解内置插件，也不需要执行 build.sh。

1. 创建工作区

在仓库根目录执行：

npm run create-plugin -- hello

目录名会被规范化为小写字母、数字、- 和 _。最终插件 id 必须为 2–64 个字符、以字母开头，且不能是 Windows 保留设备名。加 --force 可覆盖已存在的工作区。

脚手架生成如下结构：

external/hello/
├── package.json          # 插件私有 npm 依赖
├── .gitignore
├── README.md            # 开发说明（不随包发布）
├── panel/
│   ├── plugin.json
│   ├── README.md        # 插件自述（随包发布）
│   └── src/
│       ├── backend/index.ts
│       └── frontend.ts
└── daemon/
    ├── plugin.json
    ├── README.md        # Daemon 端自述（随包发布）
    └── src/
        └── backend/index.ts

panel/ 与 daemon/ 两半互相独立：只做界面就删掉 daemon/，只做节点端能力就删掉 panel/。双端插件的市场元数据只写在 panel/plugin.json；脚手架生成的 daemon/plugin.json 只含运行入口。

工作区根 package.json 只管理该插件的私有依赖，不是市场元数据。安装依赖时使用：

npm install --prefix external/hello package-name

提交 package.json 与锁文件，不要提交 node_modules/。发布编译器会把普通 JavaScript 依赖打进产物，但不会上传 node_modules、.npmrc 或原生插件的额外文件。

2. 启动开发服务

npm run dev

该命令并行启动 Daemon、Frontend、Panel 三个进程。它们以 NODE_ENV=development 运行，并把 ../external 加入监听列表，因此：

  • external/ 下的插件只在开发模式被扫描，生产构建会忽略它；

  • 后端 .ts 入口由加载器通过 ts-node 转译，前端入口进入 Vite 模块图；修改后会触发对应进程重启或浏览器刷新。

3. 验证插件已加载

脚手架生成的入口里只有一行日志：

export function apply(ctx: PanelPluginContext) {
  ctx.logger.info("Custom panel plugin loaded.");
}

在 Panel 与 Daemon 的控制台输出中看到这两行日志，即表示插件已被发现并加载。

也可以在面板的插件页面看到它 —— 每个插件都有一个开关，关闭会立即卸载插件作用域，打开会重新加载入口模块。

常见坑

external/ 不被生产构建打包。

脚手架生成的 README.md 已说明这一点。要发布插件，请走 发布到插件市场。

内置插件与外部插件的入口写法不同。

内置插件指向编译产物 backend/index.cjs，外部插件直接指向 src/backend/index.ts。详见 插件结构。

同名插件 id 冲突。

内置插件目录优先，外部工作区无法覆盖内置插件。加载器会对重复 id 告警并忽略后者。

下一步

  • 插件结构 —— 清单字段、上下文服务、注册与生命周期规则。

  • 完整示例 —— 一个贯通面板后端、前端页面与节点协议的可运行插件。

© 2026 ElementsPanel