安装插件

管理员可从插件注册表安装沙箱插件，或在 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 工作时，使用沙箱插件。