發佈外掛 | EmDash CMS Everything

外掛完成後，你可以將其發佈到 EmDash Marketplace，讓其他網站從管理後台安裝。

前置條件

發佈前請確認外掛：

具備有效的 package.json，且 "." export 指向外掛進入點
使用 definePlugin()，並提供唯一的 id 與合法的 semver version
宣告其 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、hook 名稱、路由名稱與管理端設定，但不包含可執行程式碼。

建立套件

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 不得 import 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