安裝外掛

管理員可從外掛註冊表安裝沙箱外掛，或在 astro.config.mjs 中註冊 npm 套件。基於設定的外掛可在沙箱或站點程序中執行。

為管理後台安裝做準備

註冊表安裝需要：

• 具有 plugins:manage 權限的管理員帳戶。
• 用於已下載外掛綑綁的已設定儲存。
• 可用的沙箱執行器。

在 Cloudflare Workers 上，使用 @emdash-cms/cloudflare 的 sandbox()：

import { sandbox } from "@emdash-cms/cloudflare";
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			sandboxRunner: sandbox(),
		}),
	],
});

Cloudflare 執行器使用 Worker Loader 為每個外掛建立單獨的 Worker。它需要 Workers Paid 方案以及名為 LOADER 的 worker_loaders 繫結。沙箱外掛透過 PluginBridge 存取內容、媒體、儲存、網路與郵件 API，因此站點的 Worker 進入點必須匯出該類別。

*-cloudflare 範本匯出 PluginBridge，但將 Worker Loader 繫結註解掉，以便新專案可部署到 Workers 免費方案。在搭建時啟用沙箱外掛，或遵循 Cloudflare 沙箱設定 稍後新增繫結。sandbox() 輔助函式在建置時讀取有效的 Wrangler 設定。沒有 LOADER 時，註冊表瀏覽仍可用，但設定管理的沙箱外掛不會載入，安裝或更新請求回傳 SANDBOX_NOT_AVAILABLE。

在 Node.js 上，安裝執行器及其 workerd 對等依賴：

npm install @emdash-cms/sandbox-workerd workerd

workerd 程序與 Node.js 伺服器分開執行外掛程式碼。在 EmDash 整合中選擇執行器：

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
		}),
	],
});

兩個平台的開發設定、執行階段要求、資源上限與不可用執行器錯誤見外掛沙箱。

從註冊表安裝

EmDash 驗證發布者目前已簽署的記錄，並在透過沙箱執行器載入之前檢查已下載的綑綁。外掛會出現在 Plugins 下，你可以在那裡停用或設定它。完整的驗證與信任模型見外掛註冊表。

審閱權限

同意對話框顯示外掛宣告的每一項權限。常見權限包括：

當外掛宣告時，對話框還會識別作為 Model Context Protocol（MCP）工具公開的外掛路由。完整權限模型見 Capabilities 與安全性。

更新外掛

當註冊表更新新增權限或 MCP 工具，或將路由從需認證改為公開時，需要再次確認。在你核准變更之前，EmDash 會保留已安裝的版本。

解除安裝外掛

EmDash 移除已安裝的綑綁並停止載入該外掛。外掛儲存資料預設保留。

從 npm 安裝

原生外掛與設定管理的沙箱外掛作為 npm 依賴安裝。依照套件的說明選擇 plugins: [] 或 sandboxed: []。

以下範例註冊原生 Field Kit 外掛：

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [fieldKitPlugin()],
		}),
	],
});

設定管理的外掛在你更新 npm 依賴並部署站點時變更。它們不能從管理面板安裝或移除。

選擇安裝方式

當需要 React 管理元件、Portable Text 轉譯器、頁面片段或對站點程序的直接存取時，使用原生外掛。當可透過已宣告的外掛 API 運作時，使用沙箱外掛。