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。有關管理工作階段，請參閱使用現有帳戶。

接下來閱讀什麼