安裝外掛

管理員可以從外掛註冊表安裝沙箱化外掛，也可以在 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 下，你可以在那裡停用或設定它。完整的驗證和信任模型請參閱外掛註冊表。

審閱權限

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

當外掛宣告了作為模型上下文協定（MCP）工具公開的外掛路由時，對話方塊也會標明這些路由。完整的權限模型請參閱能力與安全。

更新外掛

當註冊表更新新增權限或 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正常運作時，請使用沙箱化外掛。