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

打包与发布

本页内容

当您的沙箱插件正常工作后，发布它以便其他网站可以安装。发布仅适用于沙箱 — 原生插件通过 npm 分发。

当您发布时，CLI 会将版本记录到您自己的 Atmosphere 账户中。您自己托管 tarball — 作为 GitHub release 资产、R2、S3 或任何公共 URL — 注册表存储指向它的链接。

前提条件

  • 一个有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者（author 或 authors）和安全联系人（security 或 securityContacts）。运行 emdash-plugin validate 以确认。
  • 一个 version（在 package.json 中，或者仅注册表插件的 manifest 中）。
  • 一个用于发布的 Atmosphere 账户。

您的 Atmosphere 账户

您在 **Atmosphere 账户**下发布：一个可移植的、用户拥有的身份，用于 Bluesky 和 AT Protocol 网络中的其他应用。一个账户是您在整个网络中的单一登录，在任何地方都有相同的 @handle，您的身份和数据不绑定到任何一个应用。EmDash 使用此账户作为您的发布者身份：您发布的每个版本都是您自己账户中的记录，以您的身份签名。

EmDash 使用与其网站的 Atmosphere 登录相同的 Atmosphere 账户。

使用现有账户

如果您已经拥有 Bluesky 账户或任何其他 Atmosphere 账户，请使用其 handle 登录：

emdash-plugin login alice.bsky.social

这会在浏览器中打开您的账户提供商的登录页面。EmDash 永远看不到您的密码。emdash-plugin whoami 列出您存储的会话；emdash-plugin switch <did> 更改活动会话。

注册账户

如果您还没有 Atmosphere 账户，请通过任何提供商创建一个，然后运行 emdash-plugin login <your-handle>。您的选项：

  • 一个应用，例如 Bluesky。 注册 Bluesky 会创建一个由 Bluesky 托管的 Atmosphere 账户。这是最快的途径。
  • 独立提供商。 社区运营或注重隐私的账户托管。在 atmosphereaccount.com 浏览选项。
  • 自托管。 运行您自己的提供商以完全控制您的身份和数据。

无论您选择哪个，该账户的 @handle 就是您传递给 emdash-plugin login 的内容，账户的 DID 就是您在 manifest 中固定为 publisher 的内容。

三个步骤

以下命令登录、构建 tarball 并发布指向托管 tarball 的版本：

emdash-plugin login                     # 如果尚未登录
emdash-plugin bundle                    # 生成 dist/<slug>-<version>.tar.gz
# 将该 tarball 上传到公共 URL，然后：
emdash-plugin publish --url https://your-host/<slug>-<version>.tar.gz

bundle 在完成时打印接下来的两个步骤，包括 --url 调用，因此您不必记住格式。

Bundle

bundle 运行 build，验证，收集资产并创建 tarball。在 tarball 内，plugin.mjs 被打包为 backend.js（注册表期望的文件名）。

该命令接受以下标志：

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]
标志默认值描述
--dir当前目录插件源目录。
--out-dir, -odisttarball 的输出目录。
--validate-onlyfalse跳过 tarball，但仍生成 dist/ 工件。

Tarball 内容

文件必需描述
manifest.json是生成的 manifest：id、version、capabilities、hosts 以及从您的源代码读取的 hooks 和 routes。您不需要手动维护它。
backend.js是构建的、自包含的运行时文件（dist/plugin.mjs）。
README.md否插件文档。
icon.png否256×256 PNG。
screenshots/否最多 5 张，最大 1920×1080。

验证

bundle（和 --validate-only）检查：

  • 大小限制（RFC 0001，解压缩）： 总计 ≤ 256 KB，每个文件 ≤ 128 KB，≤ 20 个文件。gzip 压缩的 tarball 是其中的一小部分。
  • backend.js 中没有 Node 内置模块 — 沙箱代码不能导入 fs、path、child_process 等。使用 Web API，或将该逻辑移至原生插件。
  • Capability 合理性 — 名称必须在认可的集合中。
  • 信任契约一致性 — 来自 manifest 的 network:request / allowedHosts 交叉规则。
  • 资产限制 — 图标 256×256，≤ 5 张截图 ≤ 1920×1080。

要在发布前检查 tarball，请列出其内容：

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

Publish

发布会写入版本记录。tarball 必须已经托管在公共 URL 上：

emdash-plugin publish --url <hosted-tarball-url>

--url 是必需的：它是插件字节所在的位置，注册表记录指向它。要在写入记录之前验证托管 URL 是否提供您构建的确切字节，请传递 --local：

emdash-plugin publish --url https://your-host/foo-1.0.0.tar.gz --local dist/foo-1.0.0.tar.gz

publish 执行的操作：

  1. 在 --url 处获取 tarball（带有 URL 和大小保护）并从这些字节中提取 manifest。
  2. 恢复您的 Atmosphere 账户会话并检查 publisher 固定 — 活动会话必须与 manifest 的固定 publisher 匹配，否则以 MANIFEST_PUBLISHER_MISMATCH 拒绝。
  3. 首次发布时从 manifest 创建包配置文件（license、作者、安全联系人）。在后续发布中，现有配置文件获胜。
  4. 将配置文件和版本记录发布到您的账户。

首次发布时，您可以通过标志（--license、--security-email、…）而不是 manifest 提供配置文件字段；显式标志会覆盖 manifest 值，这在 CI 中很方便。--no-manifest 完全选择不使用 manifest。

版本是不可变的

已发布的版本不能被覆盖或重新发布。在再次发布之前增加 version。构建从 package.json 读取 version（参见 manifest 参考）。对于扩展的信任契约增加 major，对于新的 hooks 或 routes 增加 minor，对于修复增加 patch。

Publisher 不匹配

如果 publish 因 MANIFEST_PUBLISHER_MISMATCH 失败，则活动会话是与 manifest 的固定 publisher 不同的 Atmosphere 账户。使用 emdash-plugin switch <did> 切换到固定账户，或者如果您真的要将插件转移到新账户，请更新 manifest 中的 publisher。有关管理会话，请参阅使用现有账户。

接下来阅读什么