升级站点插件

本指南面向站点运维人员：在站点中安装插件的人。如果您编写插件，请参阅迁移到插件 CLI。

升级依赖

将 emdash 和您的插件包更新到最新版本，然后重新安装并重建：

pnpm up --latest emdash @emdash-cms/plugin-audit-log @emdash-cms/plugin-webhook-notifier @emdash-cms/plugin-atproto
pnpm build

升级后，您的站点可能无需进一步更改即可构建和运行。如果构建失败或插件停止加载，请按照以下破坏性变更逐步排查。每一项都会告诉您确切需要更改的内容。

有关每个包的完整变更列表，请参阅发布页面上的对应条目。

破坏性变更

变更：注册表发布版本可以使用 PDS blob

早期的 EmDash 版本仅从外部 URL 安装包制品。

注册表发布版本现在可以将包 bundle 作为 blob 存储在发布者的个人数据服务器（PDS）中。EmDash 通过记录范围的缓存或发布者的 PDS 解析纯 blob 发布版本，并在安装前验证获取的字节。

我应该怎么做？

在安装包制品未提供外部 URL 的发布版本之前，请先升级 EmDash。需要支持旧版站点的发布者可以继续使用 emdash-plugin publish --url <https-url> 发布包 bundle。

重命名：@emdash-cms/registry-cli 现在是 @emdash-cms/plugin-cli

早期版本将插件注册表 CLI 作为 @emdash-cms/registry-cli 发布，使用 emdash-registry 二进制文件。

该包现在是 @emdash-cms/plugin-cli，二进制文件是 emdash-plugin。旧包不再发布。

只有在您从站点仓库发布插件或运行注册表命令时才会有此依赖。大多数仅安装插件的站点从未使用过它。

我应该怎么做？

替换该包：

pnpm remove @emdash-cms/registry-cli
pnpm add -D @emdash-cms/plugin-cli

更新调用旧二进制文件的任何 package.json 脚本，将 emdash-registry 替换为 emdash-plugin：

emdash-registry publish --url https://example.com/my-plugin-1.0.0.tar.gz
emdash-plugin publish --url https://example.com/my-plugin-1.0.0.tar.gz

移除：--artifact-base-url

早期版本在清单声明了图标、横幅或截图时需要 --artifact-base-url。CLI 使用 HTTP PUT 上传这些文件。

CLI 现在将列表图片作为 atproto blob 上传到您的 Atmosphere 账户。emdash-plugin publish 默认也会在那里构建和上传包 bundle。--url 选项仍可用于外部托管的包 bundle。

我应该怎么做？

从发布脚本中移除 --artifact-base-url 和图片托管的写入凭证。从插件目录运行 emdash-plugin publish：

emdash-plugin publish

更新后的 CLI 会拒绝 --artifact-base-url 而不是忽略它，因此过时的脚本会带有迁移指引地失败。

如果命令报告 MISSING_BLOB_SCOPE，请运行 emdash-plugin logout，然后重新登录以授予 blob 上传权限。

变更：已发布的插件使用默认导出

早期版本将第一方插件作为命名导出和工厂调用公开，例如 import { auditLogPlugin } from "@emdash-cms/plugin-audit-log" 用作 auditLogPlugin()。

这些插件现在提供默认导出，您直接将其传入 plugins: 或 sandboxed:。没有工厂调用。这影响 @emdash-cms/plugin-audit-log、@emdash-cms/plugin-webhook-notifier 和 @emdash-cms/plugin-atproto。

我应该怎么做？

在 astro.config.mjs 中，去掉导入周围的花括号和插件名称后的 ()。

以下示例展示了 @emdash-cms/plugin-audit-log 的变更，它在进程内运行并放在 plugins: 中：

import { auditLogPlugin } from "@emdash-cms/plugin-audit-log";
import auditLog from "@emdash-cms/plugin-audit-log";

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

对其他包应用相同的两处编辑。@emdash-cms/plugin-atproto 和 @emdash-cms/plugin-webhook-notifier 是沙盒插件，因此它们放在 sandboxed: 而不是 plugins: 中；导入的变更是相同的。

升级后

如果第三方插件仍然发布命名导出和工厂调用，则它尚未针对此版本进行更新。请检查其更新日志。以上列出的所有第一方插件都使用默认导出形式。