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-emdashCLI 適用於 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) / 標記工程師 / 前端工程師 / 網站總監