更新 EmDash

本指南面向站点运维人员：运行基于 EmDash 构建的站点，并希望将其升级到较新发布版本的人。它涵盖 emdash 包和 @emdash-cms/cloudflare。插件包有自己的指南，即升级站点插件；对你自己的集合和字段的更改，请参阅演进已部署站点的模式。

发布与版本号

EmDash 在 1.0 版本之前发布，其版本号遵循两条规则：

• 补丁版本，例如 0.35.0 到 0.35.1，包含错误修复和小幅改进。
• 次要版本，例如 0.35 到 0.36，包含新功能和所有破坏性更改。破坏性更改会在其发布条目中标记为 Breaking，并且该条目会说明你需要采取的操作。

emdash 和 @emdash-cms/cloudflare 一同发布，共用同一个版本号。@emdash-cms/cloudflare 依赖于完全匹配的 emdash 版本，因此请一次性更新这两个包。@emdash-cms/plugin-forms 等插件包有自己的版本号，并声明它们所需的最低 emdash 版本。

发布页面为每个包和版本提供一条条目。更新之前，请阅读你已安装版本与目标版本之间的 emdash 条目；如果站点运行在 Cloudflare 上，还要阅读同一范围内的 @emdash-cms/cloudflare 条目。

模板文件不会被更新

从模板创建站点时，会把模板的文件（例如布局、组件、样式和 astro.config.mjs）复制到你的项目中。更新只会更改已安装的包，而不会动这些文件。之后对模板的更改只适用于新站点。若要在现有站点中采用某项更改，请把你的文件与 templates 目录中的当前版本进行比较，并复制你想要的更改。

更新之前

请进行可恢复的数据库备份，以及单独的媒体存储备份。EmDash 的 JSON 导出无法恢复站点，并且核心迁移没有可操作的撤销步骤。备份与恢复说明了每种数据库可用的恢复点。

请检查构建站点的机器上的 Node.js 版本，对于 Node.js 部署，还要检查服务器上的版本。创建你的第一个 EmDash 站点列出了受支持的版本。

更新包

下面的命令使用 pnpm，并且面向由 Cloudflare 模板创建的站点。对于 Node.js 部署，请省略 @emdash-cms/cloudflare。

部署并验证

像部署其他任何更改一样部署这次构建。下面的命令用于部署 Cloudflare 站点；对于 Node.js 部署，请使用新的构建重启服务器进程。

pnpm wrangler deploy

在默认的运行时迁移模式 auto 下，已部署的站点会在第一次请求时应用待处理的核心迁移。在所需的恢复点就绪之前，请勿部署含有待处理迁移的构建。若要在新代码接收流量之前应用迁移，并在之后验证已部署的数据库，请遵循管理核心数据库迁移。当已部署的数据库存在针对已安装版本的待处理迁移或未知迁移时，其 emdash migrate --check 命令会以非零状态退出。

部署之后，请打开管理后台，加载至少一个公开页面，编辑并发布一个一次性条目，并上传和获取一个一次性媒体文件。如果站点使用计划任务或沙箱插件，也请验证这些路径。

特定发布说明

大多数发布版本除了上述步骤之外不需要任何操作。下面的条目涵盖了更改了 EmDash 已存储数据的发布版本，并说明何时需要你采取操作。

已更改：引用字段绑定到 relations

reference 字段过去会把目标条目的 ID 保存在其集合表的某一列中，并在管理面板无法设置的字段选项中指明其目标集合。

引用字段现在是一个由关联支持的条目选择器，其链接存放在集合表之外。更新时，会把每个指明了目标集合的引用字段绑定到一个新的关联，并把该列中的条目 ID 作为链接复制进去，这样字段就会变成选择器，同时保持原有的选择不变。该列会保留在原处，更新不会删除任何内容。

在下列情况下，字段不会被绑定：

• 没有指明目标集合，或指明的集合已不存在
• 被标记为可搜索或已建立索引
• 需要关联 slug {collection}_{field}，而该 slug 已被占用
• 在同一条目的不同区域设置中选择了不同的条目（对任何条目而言）

最后一条涉及链接的存放位置。链接属于条目的翻译分组，因此一份选择由它的所有翻译共享，而旧的列是按区域设置划分的。区域设置之间不一致的字段没有可以延续的单一选择——合并它们会把每个区域设置的条目交给另一个区域设置，而只选取某一个区域设置的答案又会丢弃其余的——因此更新会保持该字段不变，并让两个值仍然可以在该列中读取。

有两种看起来像不一致的情况并不是。各自指明同一条目的各自翻译的区域设置，实际上是对该条目做了一次选择，因此更新会绑定该字段，并且该链接会解析到每个区域设置自己的版本。没有选择任何内容的区域设置并不与其他区域设置矛盾，因此更新会绑定该字段，并且该分组唯一的选择会适用于每个翻译，包括那个空的翻译。

未绑定的字段会保持原有的行为。它的列保存条目 ID，值可以保存和加载，并且该字段仍然可以建立索引，也可以用作内容列表过滤器。在条目编辑器中，它显示为文本框而不是选择器。

我该做什么？

在每个带有引用字段的集合中打开一个条目。显示为选择器的字段不需要任何操作。对于仍然显示为文本框的字段，请遵循绑定尚无关联的字段，它会创建关联，并把该字段已存储的 ID 作为链接复制进去。在多区域设置的站点上，请在绑定之前先确定每个翻译应当指向哪个条目，因为绑定会为所有翻译保留同一份选择。

更新后站点损坏时

• 构建失败，或你自己的某个页面在运行时出错：请阅读你所跳过版本中标记为 Breaking 的发布条目，并按照它们的说明进行更改。
• 插件加载失败：请阅读该插件自己的发布条目以及升级站点插件。
• 错误提到了某个 Astro API 或 @astrojs/* 包：EmDash 需要 Astro 6 或更高版本。Astro 的升级指南说明了如何同时更新 astro 及其官方集成。
• 若要回到之前的发布版本，请重新安装对应的先前包版本，并重新部署那个构建产物。重新安装不会撤销核心迁移。如果先前的构建产物无法使用已迁移的数据库，请停止流量，并把更新前的数据库和构建产物一起恢复；只有在更新更改了媒体时才恢复媒体。