E EmDash CMS Everything Guides, use cases, plugins, templates
简体中文

升级到 EmDash 1.0

本页内容

EmDash 1.0 移除了在 0.x 期间已弃用的 API，并将仅由 EmDash 自身加载的入口点移到 emdash/internal/ 下。本指南列出每项破坏性变更，以及你的站点需要更新的内容。

升级依赖

将 emdash 以及站点使用的其他 EmDash 包更新到最新版本，然后重新构建。以下示例会更新一个 Cloudflare 站点：

pnpm up --latest emdash @emdash-cms/cloudflare
pnpm build

如果你的部署会运行 emdash migrate，请针对升级后构建所生成的 .emdash/migrations.json 运行它。该命令会拒绝早期 EmDash 版本写入的清单。

升级后，你的站点可能无需进一步修改即可构建和运行。如果构建失败，或 EmDash 在启动时报错，请逐项处理下面的破坏性变更。

要查看每个包的完整变更列表，请参阅其在发布页面上的条目。

破坏性变更

已移除：cloudflareCache()

在早期版本中，@emdash-cms/cloudflare 的 cloudflareCache() 提供了一个路由缓存提供程序，通过 Cloudflare REST API 清除已缓存的页面。

cloudflareCache() 及其 @emdash-cms/cloudflare/cache 和 @emdash-cms/cloudflare/cache/config 入口点已被移除。导入它的站点将构建失败。

我该怎么做？

将它替换为 Astro Cloudflare 适配器的 cacheCloudflare() 提供程序，它使用 Workers Cache。设置此提供程序后，适配器会在生成的部署配置中启用 Workers Cache。

以下示例展示了 astro.config.mjs 中的改动：

import { cloudflareCache } from "@emdash-cms/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
	cache: {
		provider: cloudflareCache(),
		provider: cacheCloudflare(),
	},
});

Workers Cache 通过 cloudflare:workers 中的 cache.purge() 清除缓存，因此你可以从 Worker 中删除 CF_ZONE_ID 和 CF_CACHE_PURGE_TOKEN 密钥。KV 对象缓存（kvCache()）保持不变。

已移除：emdash/ui 中的 Comments 和 CommentForm

在早期版本中，Comments 和 CommentForm 组件同时从 emdash/ui 和 emdash/ui/comments 导出。

现在它们仅从 emdash/ui/comments 导出。从 emdash/ui 导入任一组件的站点将构建失败。

我该怎么做？

更新导入路径。组件本身没有变化。

---
import { Comments, CommentForm } from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
---

已移除：emdash dev 和 emdash auth secret

在早期版本中，emdash dev 会启动一个以本地 ./data.db 为后端的开发服务器，emdash auth secret 会为 EMDASH_AUTH_SECRET 生成一个值。

这两个命令均已移除。运行其中任何一个都会以 Unknown command 退出。

我该怎么做？

将 emdash dev 替换为站点自己的开发脚本，例如 pnpm dev，或运行 astro dev。此后站点会使用其配置中的数据库适配器。

如果你的 package.json 在 emdash 下有 url 键，请删除它。要从远程站点生成类型，请运行 emdash types --url <site-url> 或设置 EMDASH_URL。

请从脚本中移除 emdash auth secret。如果你的站点已经设置了 EMDASH_AUTH_SECRET，请保留它：EmDash 仍会读取它，以保证已存储的评论者 IP 哈希保持稳定。如需对插件密钥进行静态加密，请使用 emdash secrets generate 生成加密密钥。

已移除：experimental.registry

在早期版本中，你可以通过 emdash() 选项中的 experimental.registry 配置插件注册表。

该选项已被移除，experimental 选项本身也一并移除。仍然设置 experimental.registry 的站点会在启动时报错，错误信息会指向顶层的 registry 选项。

我该怎么做？

将该值原样移到顶层的 registry 选项。它接受相同的 URL 字符串或配置对象。

emdash({
	experimental: {
		registry: {
			aggregatorUrl: "https://registry.example.com",
			policy: { minimumReleaseAge: "48h" },
		},
	},
	registry: {
		aggregatorUrl: "https://registry.example.com",
		policy: { minimumReleaseAge: "48h" },
	},
});

如果留下了空的 experimental: {} 块，请删除它。TypeScript 配置会将其报告为错误。

已更改：内部入口点移至 emdash/internal/

在早期版本中，emdash 暴露了 emdash/routes/*、emdash/middleware/*、emdash/db/sqlite-migrations 和 emdash/plugin-test-runtime 等仅由 EmDash 自身加载的入口点。

这些入口点现在位于 emdash/internal/ 下。@emdash-cms/cloudflare 中的 D1 和 Hyperdrive 迁移执行器同样如此，它们位于 @emdash-cms/cloudflare/internal/db/ 下。它们不属于公共 API，其导出可能在任何版本中变化。通过 astro.config.mjs 中的 emdash() 配置 EmDash 的站点不受影响。

我该怎么做？

如果你的项目直接导入了这些路径中的任何一个，请将导入替换为公共 API：

  • 要配置数据库、对象缓存或媒体提供程序，请使用 emdash/db 中的 sqlite()、libsql() 或 postgres()，emdash/astro 中的 memoryCache()，或 emdash/media 中的 localMedia()。
  • 要测试插件，请使用 @emdash-cms/plugin-test，而不是 emdash/plugin-test-runtime。
  • 要在 EmDash 的中间件之前运行你自己的中间件，请设置 emdash() 的 middleware.outer 选项。

内部的认证、初始设置、重定向和请求上下文中间件没有公共的替代方案。

弃用

已弃用：早期的插件能力名称

在早期版本中，插件可以使用 read:content、network:fetch 和 page:inject 等名称声明能力，而不会有任何警告。

对于每个声明了这些已弃用名称的插件，EmDash 会在启动时记录一条警告，并列出各自当前的替代名称（例如 read:content → content:read）。已弃用的名称在整个 1.x 期间仍可使用。

我该怎么做？

如果你使用的某个插件触发了该警告，请将其更新到使用当前名称的版本，或请作者发布这样的版本。如果你是该插件的维护者，请在其清单中重命名这些能力。当前名称请参阅能力与安全。