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 期間仍可使用。

我該怎麼做？

如果你使用的某個外掛觸發了該警告，請將其更新到使用目前名稱的版本，或請作者發布這樣的版本。如果你是該外掛的維護者，請在其清單中重新命名這些能力。目前名稱請參閱能力與安全。