更新 EmDash

本指南面向站点运维人员：运行基于 EmDash 构建的站点，并希望将其升级到较新发布版本的人。更新器会处理项目中每一个直接的 emdash 和 @emdash-cms/* 依赖项。对你自己的集合和字段的更改，请参阅演进已部署站点的模式。

发布兼容性

EmDash 遵循语义化版本：

• 补丁版本包含向后兼容的修复和小幅改进。
• 次要版本包含向后兼容的功能。
• 主要版本可能需要对现有项目做出更改。其发布条目会指明受影响的项目和所需的操作。

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

发布页面为每个包和版本提供一条条目。upgrade-emdash 会根据每个直接包精确的 GitHub 发布标签获取其变更日志范围。它会移除自动生成的依赖项升级条目，完整保留手写的主要、次要和补丁版本条目，并对跨包重复出现的条目去重。

模板文件不会被更新

从模板创建站点时，会把模板的文件（例如布局、组件、样式和 astro.config.mjs）复制到你的项目中。更新器会修改直接的 EmDash 依赖项，并刷新 EmDash 的 agent skills。站点的应用程序文件和配置文件则留给项目负责人或 agent 根据升级工作单来修改。之后对模板的更改只适用于新站点。若要在现有站点中采用某项更改，请把你的文件与 templates 目录中的当前版本进行比较，并复制你想要的更改。

更新之前

更新器会在不连接站点数据库的情况下修改项目文件和已安装的包，因此运行前不要求专门为升级做备份。安装完成后，.emdash/UPGRADE.md 会列出新增的核心迁移（如果有）。

在启动或部署升级后的应用程序之前，如果工作单列出了新增的迁移、emdash migrate --status 报告存在更早的待处理迁移，或某个发布条目要求执行会更改数据的项目操作，请先创建恢复点。针对所配置的数据库，请遵循备份与恢复。EmDash 的 JSON 备份无法恢复站点。

更新器要求 emdash 0.35.0 或更高版本，这是第一个会报告其核心迁移的发布版本。对于更旧的站点，请先创建恢复点，用项目的包管理器将 emdash 和其他直接的 @emdash-cms/* 包更新到 0.35.0，并查阅各包截至该版本的变更日志。然后再运行更新器完成其余的更新。

更新器从 node_modules 读取包，因此不支持 Yarn Plug’n’Play 安装。对于使用 Plug’n’Play 的 Yarn 项目，请先在 .yarnrc.yml 中设置 nodeLinker: node-modules 并运行 yarn install，然后再运行更新器。

请检查构建站点的机器上的 Node.js 版本；如果是 Node.js 部署，还要检查服务器上的版本。支持的版本见创建你的第一个 EmDash 站点。

规划并应用更新

在站点的项目目录中运行更新器。它会读取已安装的包版本和核心迁移标识，然后为每个直接的 EmDash 包分别解析所选的 npm dist-tag。默认标签是 latest；使用 --to next、--to beta 或其他 dist-tag 可选择发布渠道。--to 不接受精确的版本号。

部署并验证

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

pnpm wrangler deploy

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

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

特定发布说明

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

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

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

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

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

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

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

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

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

我该做什么？

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

已修复：可搜索的引用字段

在早期版本中，标记为 searchable 的引用字段会破坏其所在的集合：向已开启搜索的集合添加这样的字段会失败；而在 seed 开启搜索之后，在该集合中创建或保存任何条目都会失败，服务器日志中会出现 no such column。

站点搜索和内容列表搜索会忽略绑定到 relation 的引用字段上的 searchable 标志。更新无法修复已被 seed 破坏的集合，因为它的搜索索引仍然期待该字段。

我该做什么？

如果在某个集合中创建或保存条目失败，且服务器日志显示 no such column，请在 Content Types 下打开该集合，取消勾选 Search 复选框并保存。然后再次勾选 Search 并保存。这样会重建该集合的搜索索引，集合即可再次接受新建和编辑的条目。

更新后站点损坏时

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