Topics

EmDash 正式版發布。我把版本從 0.22 升級到 1.2 試試看

  • column

2026年09月28日,EmDash 1.0 正式發布。
EmDash 是 Cloudflare 開發、以 Astro 為基礎的開源 CMS,後台管理介面會整個內嵌在 Astro 網站中,並以 Cloudflare Workers + D1 + R2 運作。
若說它是 Astro 版的 WordPress,大致上是相符的。

先前的文章中提到,從 microCMS 遷移過來的公司內部部落格「ゆるろぐ」,一直停留在六月升上去的 0.22 版,因此這次趁機一口氣升級到最新的 1.2.0。

1.0 的重點包括穩定性與升級的安全性、在沙箱中運行的外掛,以及面向 Agent 的 MCP 伺服器。

結論是,遷移一天就完成了,但陷阱不少。
如果抱著「已經是 1.0 了,應該很穩定」的輕鬆心態開始,就會卡在 EmDash 本體之外的周邊相依套件上。

前提:從 0.22 升到 1.2 只能手動進行

1.2 新增了官方升級 CLI upgrade-emdash。
它會更新相依套件,並產生專屬於該網站的 UPGRADE.md,但只支援 0.35 以上的版本,因此從 0.22 開始無法使用。

從 0.22 到 1.2 之間夾了 47 個資料庫遷移檔,而且也有幾項相當具破壞性的變更。
這並不是「先跑一下 npm install emdash@latest」就能解決的事。

1. 先備份,並在本機複製一份正式環境的資料庫

npx wrangler d1 export <database-name> --remote --output=backups/pre-1.2.sql

把它匯入本機的 D1,用與正式環境相同的資料測試遷移。

2. 更新依賴套件

套件

遷移前

遷移後

emdash / @emdash-cms/cloudflare / @emdash-cms/admin

0.22.0

1.2.0

@emdash-cms/plugin-forms

0.1.1

0.2.9

astro

6.1.2

6.4.8

wrangler

4.80

4.148

wrangler 需要升級至 emdash 1.2 的 peer 相依要求(4.99 以上),因此這次一併移除了 0.22 時期的暫時性修正。
@astrojs/cloudflare 已符合 peer 相依要求,所以此時仍維持在 13.1.6。這正是下一個陷阱的成因。

  • OAuth 路由的 patch-package:為了規避 0.22 的錯誤而套用的修補,已在主程式中修復
  • 管理後台的 CSS 注入:0.22 的 admin 使用的是針對 UI 函式庫 kumo 2.4 的 CSS,但 lockfile 卻鎖定了 2.6,導致登入與發佈等強調按鈕變成「透明背景搭配白色文字」而無法辨識。1.2 已在主程式端修正

3. dev 無法啟動(陷阱:miniflare 版本世代不一致)

升級相依套件後執行 npm run dev 無法啟動,原因是 miniflare 版本世代不一致。
wrangler 4.148 使用的是 miniflare 5,會將本地 D1 狀態(.wrangler/state/v3/ 底下)的 _cf_ALARM 資料表更新為 3 欄。
另一方面,@astrojs/cloudflare 13.1.6 內建的 miniflare 為 4,因欄位數不一致而無法讀取本地狀態。

解決方法是把先前維持不動的 @astrojs/cloudflare 一併升級,讓 miniflare 版本與 wrangler 對齊。只要記住「wrangler 與轉接器的 miniflare 版本必須一致」,下次就能一次到位。

此外,0.22 版中已移除 emdash dev 指令,因此 dev 腳本已改回 astro dev。資料遷移與型別產生會在 astro dev 啟動時執行。

4. staging 的選單消失了(陷阱:seed.json 的 menus)

dev 啟動後,90 支遷移腳本都順利執行,我將內容推送到 staging 並開啟管理後台,發現日文的全域導覽列是空的。

原因在於 seed/seed.json 中的 menus 與 widgetAreas。
EmDash 的 seed 處理程序在遇到同名的選單或小工具區域時,會先刪除所有項目,再以空白內容重新建立。
seed.json 中仍保留了作為範本的 "items": [] 選單定義,因此每次執行 seed 時選單都會被重設。

解決方式是將 menus 與 widgetAreas 的鍵直接刪除。
選單內容應由管理後台管理,因此沒有必要在 seed 中保存。

5. 英文文章的連結變成 /en/posts/en/slug(陷阱:entry.id 的語系前綴)

這是 1.2 版的規格變更。
在多語言網站中,getEmDashCollection() 回傳的 entry.id 會帶有語系前綴。若為英文文章,則為 en/my-post。

ゆるろぐ 在組合文章 URL 時是從 entry.id 產生,因此英文文章的連結會變成 /en/posts/en/my-post 這種重複路徑。
我們已將列表、精選、搜尋結果、RSS,以及組合 canonical 與 URL 的所有位置,全部改為使用 entry.data.slug。
entry.data.slug 的型別為 string | null,因此接收端的型別也需要一併調整。

建議先分清各自的用途:entry.id 是鍵,entry.data.slug 是網址,entry.data.id 是資料庫的 ULID(用於 API 呼叫)。

6. 每分鐘都出現錯誤(陷阱:Cron Trigger 與 Worker 進入點)

在 1.x 中,預約發佈與外掛的定期排程是由 Worker 的 scheduled() 處理常式來驅動。
Cloudflare 沒有內部計時器,因此若沒有 Cron Trigger,預約文章到了發佈時間也不會出現。
所以我在 wrangler.jsonc 中加入了 Cron Trigger。

"triggers": { "crons": ["* * * * *"] }

接著每分鐘都會出現 "Handler does not export a scheduled() function"。
這是因為 Worker 的進入點沒有匯出 scheduled()。
解決方式是將 src/worker.ts 替換為官方的進入點。

export { default, PluginBridge } from "@emdash-cms/cloudflare/worker";

如此一來,除了 fetch 和 scheduled 之外,沙箱型外掛所用的 PluginBridge 也都齊備了。

實際使用後的感想

升級到 1.2 後覺得好的地方。

  • 編輯器經過改版,更容易使用。斜線選單已分組,工具列也會跟隨捲動。手機上也能使用。
  • 影片區塊已內建為標準功能。先前我用自製外掛嵌入影片,之後打算找機會替換掉。
  • 0.22 時代的臨時修補全都能拿掉了。 patch-package 和 CSS 注入也都不需要了。

值得注意的地方。

  • 從 1.0 到 1.2 只用了 10 天,更新速度很快。短期內似乎需要每次小版本更新都先在 staging 環境確認。

總結

  • 0.22 → 1.2 需要手動遷移。upgrade-emdash CLI 適用於 0.35 以上版本。
  • wrangler與轉接器的miniflare版本需保持一致→版本不一致時dev無法啟動
  • 不要在seed.json中保留menus / widgetAreas的空白範本→每次seed都會被清除
  • 多語言網站的entry.id會帶有語系前綴→網址請改用entry.data.slug產生
  • 若要新增Cron Trigger,請將Worker進入點設為@emdash-cms/cloudflare/worker

這些問題一旦搞懂,都只是幾行的修正,但邊查邊進行時,花費的時間比預期多得多。

話雖如此,0.22時期套用的補丁與CSS臨時修正能全部移除,也證明了正式發布前許多細小的錯誤已陸續被修復。
半年前還只是「試著換上去看看」的心態,但經過1.0,只要預留跟進更新的工夫,我認為它已成為足以納入實際營運選項中認真考慮的CMS。

關於撰寫本文的人

從 DTP 踏入網頁世界,不知不覺間,標記、前端、專案指導與無障礙,樣樣精通的「技藝仙人」。自 Liberogic 創業初期就跨領域活躍,如今是公司內部的活字典般的存在。最近沉迷於運用提示詞提升效率的探索,想著「無障礙相關的工作,能不能更依賴 AI 呢?」技術與思考,仍在持續進化中

二俣 步

IAAP認證網頁無障礙專員(WAS) / 標記工程師 / 前端工程師 / 網站總監

查看此員工的文章

我們的優勢在於穩健的團隊體制與快速的應對能力

Liberogic 由經驗豐富的資深人員積極推動專案,因此獲得客戶的高度評價。
我們會妥善指派專案經理與總監,致力於順利推進整體專案。 我們採取依據專案需求適才適所分配資源的方式,避免因全程投入而增加不必要的成本,並且在掌握業務內容、製作與提交估價方面的速度也廣受好評。

注: 本公司不積極承接類似 SES 的駐點業務等,敬請事先諒解。

可搭配 Slack、Teams、Redmine、Backlog、Asana、Jira、Notion、Google Workspace、Zoom、Webex 等幾乎所有主要的專案管理工具與聊天工具使用。

歡迎諮詢您的 Web 相關問題。

案例分析