插件开发完成后，你可以将其发布到 EmDash Marketplace，供其他站点从管理后台安装。
前置条件
发布前请确认插件：
- 具有有效的
package.json，且"."export 指向插件入口 - 使用
definePlugin()，并提供唯一的id与合法的 semverversion - 声明其
capabilities（需要访问哪些 API）
包格式
已发布插件以包含以下内容的 .tar.gz 压缩包分发：
| 文件 | 必填 | 说明 |
|---|---|---|
manifest.json | 是 | 从 definePlugin() 提取的插件元数据 |
backend.js | 否 | 打包后的沙箱代码（自包含 ES 模块） |
admin.js | 否 | 打包后的管理后台 UI 代码 |
README.md | 否 | 插件文档 |
icon.png | 否 | 插件图标（256×256 PNG） |
screenshots/ | 否 | 最多 5 张截图（PNG/JPEG，最大 1920×1080） |
manifest.json 会根据 definePlugin() 调用自动生成，包含插件 ID、版本、capabilities、钩子名、路由名和管理端配置，但不包含可执行代码。
构建包
emdash plugin bundle 命令会从插件源码生成 tarball：
cd packages/plugins/my-plugin
emdash plugin bundle该命令会：
- 读取
package.json以定位入口 - 使用 tsdown 构建主入口并提取 manifest
- 打包
backend.js（压缩、tree-shake、自包含） - 若存在
"./admin"export，则打包admin.js - 收集资源（README、图标、截图）
- 校验包（大小限制、backend 不得引入 Node.js 内置模块）
- 将
{id}-{version}.tar.gz写入dist/
入口解析
bundle 命令通过 package.json 的 exports 查找代码：
{
"exports": {
".": { "import": "./dist/index.mjs" },
"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
"./admin": { "import": "./dist/admin.mjs" }
}
}| Export | 用途 | 构建方式 |
|---|---|---|
"." | 主入口 — 用于提取 manifest | Externals：emdash、@emdash-cms/* |
"./sandbox" | 在沙箱中运行的后端代码 | 完全自包含（无 externals） |
"./admin" | 管理端 UI 组件 | 完全自包含 |
若缺少 "./sandbox"，命令会回退查找 src/sandbox-entry.ts。
选项
emdash plugin bundle [--dir <path>] [--outDir <path>]| 标志 | 默认值 | 说明 |
|---|---|---|
--dir | 当前目录 | 插件源码目录 |
--outDir, -o | dist | tarball 输出目录 |
校验
bundle 命令会检查：
- 大小限制 — 总包体积须小于 5MB
- 禁止 Node.js 内置模块 —
backend.js不得导入fs、path、child_process等（沙箱代码在 V8 isolate 中运行，而非 Node.js） - 图标尺寸 —
icon.png应为 256×256（不符会警告但仍会包含） - 截图限制 — 最多 5 张，最大 1920×1080
发布
emdash plugin publish 命令会将 tarball 上传到 Marketplace：
emdash plugin publish默认会找到 dist/ 中最新的 .tar.gz 并上传。你也可以显式指定 tarball，或在发布前先构建：
# 显式指定 tarball 路径
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz
# 先构建再发布
emdash plugin publish --build认证
首次发布时，CLI 会通过 GitHub 完成认证：
- CLI 在浏览器中打开 GitHub 设备授权页面
- 在终端显示的设备码处输入该码
- GitHub 颁发 access token
- CLI 将其交换为 Marketplace JWT（保存在
~/.config/emdash/auth.json）
令牌有效期为 30 天。过期后，下次发布时会提示重新认证。
也可单独管理登录状态：
# 仅登录，不发布
emdash plugin login
# 登出（清除已存令牌）
emdash plugin logout首次注册
若插件 ID 尚不存在于 Marketplace，emdash plugin publish 会在上传首个版本前自动完成注册。
版本要求
每次发布的版本 semver 必须高于上一版。不能覆盖或重复发布已有版本。
安全审计
每个已发布版本都会经过自动安全审计。Marketplace 会扫描 backend.js 与 admin.js，检测：
- 数据外泄模式
- 通过设置窃取凭据
- 混淆代码
- 资源滥用（如挖矿等）
- 可疑网络行为
审计结果为 pass、warn 或 fail，并显示在插件的 Marketplace 页面上。根据 Marketplace 的强制执行策略，fail 可能会阻止发布。
选项
emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]| 标志 | 默认值 | 说明 |
|---|---|---|
--tarball | dist/ 中最新 .tar.gz | 显式 tarball 路径 |
--build | false | 发布前执行 emdash plugin bundle |
--dir | 当前目录 | 插件目录（与 --build 联用） |
--registry | https://marketplace.emdashcms.com | Marketplace URL |
完整流程
典型发布周期：
# 1. 完成修改
# 2. 在 definePlugin() 与 package.json 中提升版本
# 3. 一步完成打包与发布
emdash plugin publish --build若希望先检查包内容：
# 构建 tarball
emdash plugin bundle
# 查看输出
tar tzf dist/my-plugin-1.1.0.tar.gz
# 发布
emdash plugin publish