當你的沙盒外掛可以正常運作後，就可以將其發佈到 EmDash 市集，讓其他網站能夠從管理後台一鍵安裝。發佈流程僅適用於沙盒外掛——原生外掛透過 npm 發行，不會被打包成市集 tarball。
前置條件
發佈前，請確保你的外掛：
- 擁有一個
package.json，其中包含"."匯出（描述符）和"./sandbox"匯出（執行時進入點）。 - 在描述符上使用
format: "standard"。 - 擁有唯一的
id和有效的 semverversion。 - 在描述符上準確宣告其
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這將：
- 讀取你的
package.json以尋找進入點。 - 建構描述符進入點以提取 ID、版本、capabilities 和管理組態。
- 從
"./sandbox"匯出打包backend.js——經過壓縮、tree-shake，完全自包含。 - 如果存在
"./admin"匯出，則打包admin.js。 - 收集資源（README、圖示、截圖）。
- 驗證套件（大小限制、
backend.js中不能有 Node.js 內建模組、capabilities 檢查）。 - 將
{id}-{version}.tar.gz寫入dist/。
進入點解析
bundle 命令透過 package.json 的匯出尋找你的程式碼：
{
"exports": {
".": { "import": "./dist/index.mjs" },
"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
"./admin": { "import": "./dist/admin.mjs" }
}
}| 匯出 | 目的 | 建構方式 |
|---|---|---|
"." | 描述符——用於提取 manifest | Externals: 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, -o | dist | tarball 的輸出目錄 |
驗證
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 對你進行認證：
- CLI 在你的瀏覽器中開啟 GitHub 的裝置授權頁面。
- 你輸入終端機中顯示的代碼。
- GitHub 發放存取權杖。
- 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>]| 標誌 | 預設值 | 說明 |
|---|---|---|
--tarball | dist/ 中最新的 .tar.gz | 明確的 tarball 路徑 |
--build | false | 在發佈前執行 emdash plugin bundle |
--dir | 目前目錄 | 外掛目錄（與 --build 一起使用） |
--registry | https://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