EmDash CMS Cloudflare 免費方案生產環境實務手冊

發布於 2026-04-08 作者 Emdash Cms Everything

執行摘要

你可以在 Cloudflare 免費方案上，以核心 CMS 工作流程運行 EmDash 生產環境。
必須接受的事實：沙盒化外掛執行不可用，因此必須從設定中移除 worker_loaders。

本指南以穩定優先，而非最大化功能面。

免費方案上的能力邊界

可用

• EmDash 核心網站與後台流程
• 以 D1 為後盾的內容資料
• 以 R2 為後盾的媒體儲存（在免費用量內）
• Workers 部署與路由

不可用

• 用於沙盒化外掛的 Dynamic Workers
• 類似外掛市集、不受信任執行期的執行方式

若你的上線依賴沙盒化的第三方外掛執行，免費方案不足。

部署前檢查清單

執行部署指令前完成所有檢查：

• 已完成 Wrangler 驗證（wrangler login）
• 專案可在本機建置，且不依賴僅雲端才有的假設
• wrangler.jsonc 的 D1 與 R2 綁定與執行期設定一致
• 已為免費方案移除 worker_loaders 項目
• 套件管理工具選擇一致（npm 或 pnpm，勿混用）

資源開通順序

請依此順序開通資源，以降低綁定變更造成的混亂：

1. 建立 D1 資料庫
2. 建立或啟用 R2，再建立 bucket
3. 以確切名稱與 ID 更新 wrangler.jsonc
4. 建置並部署 Worker

原因：D1 ID 與 bucket 名稱會成為環境綁定的真實來源。

# 先開通 D1
npx wrangler d1 create your-db-name

# 再開通 R2 bucket
npx wrangler r2 bucket create your-media-bucket

免費方案最小 wrangler.jsonc 形狀

下列骨架刻意保持精簡：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "your-site-name",
  "main": "./src/worker.ts",
  "compatibility_date": "2026-04-08",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "your-db-name",
      "database_id": "replace-with-d1-id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "your-media-bucket"
    }
  ]
}

免費方案不要放 worker_loaders 區塊。

建置與部署流程

在 EmDash 專案根目錄執行：

# 選定一種套件管理工具並貫徹使用
npm run build
npm run deploy

若專案以 pnpm 為主：

pnpm build
pnpm deploy

除非刻意同步 lockfile，否則避免在同一次部署流程中混用 npm 與 pnpm。

部署後驗證檢查清單

依此順序驗證：

1. 前台 URL 可解析並回傳預期內容
2. 後台 URL（/_emdash/admin）可連線
3. 首次後台設定可順利完成
4. 建立並發佈一則測試內容
5. 上傳一個媒體檔並確認可取回

僅路由可達不算部署完成；必須驗證資料寫入路徑。

常見故障模式與最短修復

故障：部署成功，後台無法初始化

可能原因：執行期整合與 wrangler.jsonc 之間綁定名稱不一致。

修復步驟：

1. 確認綁定名稱（DB、MEDIA）在各處完全相同
2. 修正設定後重新部署
3. 重試後台初始化

故障：R2 指令被帳戶提示擋下

可能原因：尚未在儀表板啟用 R2。

修復步驟：

1. 在 Cloudflare 儀表板啟用 R2
2. 接受計費條款（免費額度仍適用）
3. 重新執行建立 bucket 指令

故障：免費方案出現與外掛相關的執行期錯誤

可能原因：殘留沙盒設定。

修復步驟：

1. 移除 worker_loaders
2. 停用沙盒專屬的外掛設定
3. 重新部署並重測

回滾策略

採保守回滾政策：

• 為最後已知良好的部署 commit 打標籤
• 若生產環境出現倒退，重新部署先前已標籤的 commit
• 在流量穩定前，延後 schema 或外掛變更

在事故窗口中，快速回滾通常勝過深度熱修。

何時從免費升級到付費

僅在下列任一為真時升級：

• 你需要沙盒化的不受信任外掛執行
• 流量或儲存經常超出免費額度
• 治理要求更強的外掛執行期隔離

不要只因計費畫面上含糊的用字就升級；僅因具體能力需求而升級。