E EmDash CMS Everything Guides, use cases, plugins, templates
简体中文

打包与发布

本页内容

当你的沙箱插件可以正常工作后，就可以将其发布到 EmDash 市场，让其他网站能够从管理后台一键安装。发布流程仅适用于沙箱插件——原生插件通过 npm 分发，不会被打包成市场 tarball。

前置条件

发布前，请确保你的插件：

  • 拥有一个 package.json，其中包含 "." 导出（描述符）和 "./sandbox" 导出（运行时入口）。
  • 在描述符上使用 format: "standard"。
  • 拥有唯一的 id 和有效的 semver version。
  • 在描述符上准确声明其 capabilities 和 allowedHosts。

包格式

已发布的插件以 .tar.gz tarball 的形式分发，包含：

文件必需描述
manifest.json是从描述符和沙箱入口提取的插件元数据
backend.js是打包的沙箱代码（自包含的 ES 模块）
admin.js否打包的管理界面代码（仅当 Block Kit 交互提供 JS 时）
README.md否插件文档
icon.png否插件图标（256×256 PNG）
screenshots/否最多 5 张截图（PNG/JPEG，最大 1920×1080）

manifest.json 会自动生成。它包含插件 ID、版本、capabilities、允许的主机、钩子名称、路由名称和管理配置——但不包含可执行代码。

构建包

cd packages/plugins/my-plugin
emdash plugin bundle

这将：

  1. 读取你的 package.json 以查找入口点。
  2. 构建描述符入口以提取 ID、版本、capabilities 和管理配置。
  3. 从 "./sandbox" 导出打包 backend.js——经过压缩、tree-shake，完全自包含。
  4. 如果存在 "./admin" 导出，则打包 admin.js。
  5. 收集资源（README、图标、截图）。
  6. 验证包（大小限制、backend.js 中不能有 Node.js 内置模块、capabilities 检查）。
  7. 将 {id}-{version}.tar.gz 写入 dist/。

入口点解析

bundle 命令通过 package.json 的导出查找你的代码：

{
	"exports": {
		".": { "import": "./dist/index.mjs" },
		"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
		"./admin": { "import": "./dist/admin.mjs" }
	}
}
导出目的构建方式
"."描述符——用于提取 manifestExternals: emdash, @emdash-cms/*
"./sandbox"在沙箱中执行的运行时代码（hooks、routes）完全自包含（无 externals）
"./admin"管理界面组件（仅当你提供时）完全自包含

如果缺少 "./sandbox"，命令会回退查找 src/sandbox-entry.ts。打包器会自动将 dist 路径映射回源代码——如果你的 "." 导出指向 ./dist/index.mjs，它会找到并构建 src/index.ts。

选项

emdash plugin bundle [--dir <path>] [--outDir <path>]
标志默认值描述
--dir当前目录插件源代码目录
--outDir, -odisttarball 的输出目录

验证

bundle 命令会检查：

  • 大小限制——总包大小必须小于 5 MB。
  • backend.js 中不能有 Node.js 内置模块——沙箱代码不能导入 fs、path、child_process 等。用 Web API 替换它们或将逻辑移至原生插件。
  • Capability 白名单——声明的 capabilities 必须在已知集合中（拼写错误会失败）。
  • 已弃用的 capability 名称在此处触发警告，在发布时触发硬失败。
  • 没有 allowedHosts 的 network:request 触发警告（如果主机由操作员在运行时配置，请考虑 network:request:unrestricted，或明确列出主机）。
  • 图标尺寸——icon.png 应为 256×256（如果错误会警告；但仍会包含）。
  • 截图限制——最多 5 张，最大 1920×1080。

发布

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 对你进行认证：

  1. CLI 在你的浏览器中打开 GitHub 的设备授权页面。
  2. 你输入终端中显示的代码。
  3. GitHub 发放访问令牌。
  4. CLI 将其交换为市场 JWT（存储在 ~/.config/emdash/auth.json 中）。

令牌持续 30 天。过期后，下次发布时会提示你重新认证。

你可以单独管理认证：

emdash plugin login    # 登录但不发布
emdash plugin logout   # 清除已存储的令牌

首次注册

如果你的插件 ID 尚未被市场识别，emdash plugin publish 会在上传第一个版本之前自动注册它。

版本要求

每个发布的版本必须具有比上一个更高的 semver。你不能覆盖或重新发布现有版本——在再次发布之前，在 package.json 和描述符中都提升版本。

安全审计

每个发布的版本都会经过自动安全审计。审计会扫描 backend.js 和 admin.js 以查找：

  • 数据泄露模式
  • 通过设置收集凭据
  • 混淆代码
  • 资源滥用（加密货币挖矿等）
  • 可疑的网络活动

审计会产生 pass、warn 或 fail 的判决，显示在插件的市场列表上。根据市场的执行级别，fail 判决可能会完全阻止发布。

选项

emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]
标志默认值描述
--tarballdist/ 中最新的 .tar.gz明确的 tarball 路径
--buildfalse在发布前运行 emdash plugin bundle
--dir当前目录插件目录（与 --build 一起使用）
--registryhttps://marketplace.emdashcms.com市场 URL

完整工作流

典型的发布周期：

# 1. 进行更改
# 2. 在 src/index.ts 和 package.json 中提升版本
# 3. 打包并发布
emdash plugin publish --build

如果你想先检查包：

emdash plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz
emdash plugin publish