安装插件

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