更新 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 下，已部署的站台會在第一次請求時套用待處理的核心遷移。在所需的復原點就緒之前，請勿部署含有待處理遷移的建置。若要在新程式碼接收流量之前套用遷移，並在之後驗證已部署的資料庫，請遵循管理核心資料庫遷移。當已部署的資料庫存在針對已安裝版本的待處理遷移或未知遷移時，其 emdash migrate --check 指令會以非零狀態結束。

部署之後，請開啟管理後台，載入至少一個公開頁面，編輯並發布一個一次性條目，並上傳和擷取一個一次性媒體檔案。如果站台使用排程工作或沙箱外掛程式，也請驗證這些路徑。

特定發佈說明

大多數發佈版本除了上述步驟之外不需要任何動作。下面的條目涵蓋了變更了 EmDash 已儲存資料的發佈版本，並說明何時需要你採取動作。

已變更：參照欄位繫結到 relations

reference 欄位過去會把目標條目的 ID 儲存在其集合資料表的某一欄中，並在管理面板無法設定的欄位選項中指明其目標集合。

參照欄位現在是一個由關聯支援的條目選擇器，其連結存放在集合資料表之外。更新時，會把每個指明了目標集合的參照欄位繫結到一個新的關聯，並把該欄中的條目 ID 作為連結複製進去，這樣欄位就會變成選擇器，同時保持原有的選擇不變。該欄會保留在原處，更新不會刪除任何內容。

在下列情況下，欄位不會被繫結：

• 沒有指明目標集合，或指明的集合已不存在
• 被標記為可搜尋或已建立索引
• 需要關聯 slug {collection}_{field}，而該 slug 已被占用
• 在同一條目的不同區域設定中選擇了不同的條目（對任何條目而言）

最後一條涉及連結的存放位置。連結屬於條目的翻譯群組，因此一份選擇由它的所有翻譯共用，而舊的欄是按區域設定劃分的。區域設定之間不一致的欄位沒有可以延續的單一選擇——合併它們會把每個區域設定的條目交給另一個區域設定，而只選取某一個區域設定的答案又會丟棄其餘的——因此更新會保持該欄位不變，並讓兩個值仍然可以在該欄中讀取。

有兩種看起來像不一致的情況並不是。各自指明同一條目的各自翻譯的區域設定，實際上是對該條目做了一次選擇，因此更新會繫結該欄位，並且該連結會解析到每個區域設定自己的版本。沒有選擇任何內容的區域設定並不與其他區域設定矛盾，因此更新會繫結該欄位，並且該群組唯一的選擇會適用於每個翻譯，包括那個空的翻譯。

未繫結的欄位會保持原有的行為。它的欄保存條目 ID，值可以儲存和載入，並且該欄位仍然可以建立索引，也可以用作內容清單篩選器。在條目編輯器中，它顯示為文字方塊而不是選擇器。

我該做什麼？

在每個帶有參照欄位的集合中開啟一個條目。顯示為選擇器的欄位不需要任何動作。對於仍然顯示為文字方塊的欄位，請遵循繫結尚無關聯的欄位，它會建立關聯，並把該欄位已儲存的 ID 作為連結複製進去。在多區域設定的站台上，請在繫結之前先確定每個翻譯應當指向哪個條目，因為繫結會為所有翻譯保留同一份選擇。

更新後站台損壞時

• 建置失敗，或你自己的某個頁面在執行階段出錯：請閱讀你所跳過版本中標記為 Breaking 的發佈條目，並按照它們的說明進行變更。
• 外掛程式載入失敗：請閱讀該外掛程式自己的發佈條目以及升級站台外掛程式。
• 錯誤提到了某個 Astro API 或 @astrojs/* 套件：EmDash 需要 Astro 6 或更高版本。Astro 的升級指南說明了如何同時更新 astro 及其官方整合。
• 若要回到之前的發佈版本，請重新安裝對應的先前套件版本，並重新部署那個建置成品。重新安裝不會復原核心遷移。如果先前的建置成品無法使用已遷移的資料庫，請停止流量，並把更新前的資料庫和建置成品一起還原；只有在更新變更了媒體時才還原媒體。