EmDash CMS Cloudflare 免费套餐生产部署手册

发布于 2026-04-08 作者 Emdash Cms Everything

摘要

你可以在 Cloudflare 免费套餐上运行 EmDash 的生产环境，覆盖核心 CMS 工作流。
需要接受的前提：沙箱化插件执行不可用，因此必须从配置中移除 worker_loaders。

本指南优先追求稳定，而非功能面最大化。

免费套餐上的能力边界

可用

• EmDash 核心站点与管理流程
• 基于 D1 的内容数据
• 基于 R2 的媒体存储（在免费用量内）
• Workers 部署与路由

不可用

• 用于沙箱化插件的动态 Workers
• 类应用商店、不可信运行时的插件执行

若上线依赖第三方插件的沙箱执行，免费套餐不足。

部署前检查清单

在运行部署命令前完成全部检查：

• 已完成 Wrangler 认证（已执行 wrangler login）
• 项目在本地可构建，且不依赖仅云端才有的假设
• wrangler.jsonc 中 D1、R2 绑定与运行时配置一致
• 为免费套餐已移除 worker_loaders 项
• 包管理器选择一致（npm 或 pnpm，勿混用）

资源开通顺序

按此顺序开通资源，可减少绑定反复调整：

1. 创建 D1 数据库
2. 创建或启用 R2，再创建存储桶
3. 用准确名称与 ID 更新 wrangler.jsonc
4. 构建并部署 Worker

原因：D1 ID 与存储桶名称会成为环境绑定的事实来源。

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

# 再开通 R2 存储桶
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

除非有意同步锁文件，否则避免在同一次部署会话中混用 npm 与 pnpm。

部署后校验清单

按此顺序验证：

1. 前台 URL 可解析并返回预期内容
2. 管理地址（/_emdash/admin）可访问
3. 首次管理员初始化顺利完成
4. 创建并发布一条测试内容
5. 上传一个媒体文件并确认可拉取

仅路由可达不算完成部署；必须验证数据写入路径。

高频故障与最短修复

故障：部署成功，管理端无法初始化

可能原因：运行时集成与 wrangler.jsonc 之间绑定名不一致。

处理：

1. 确认绑定名（DB、MEDIA）在各处完全一致
2. 修正配置后重新部署
3. 重试管理端初始化

故障：R2 命令被账户提示拦截

可能原因：控制台尚未启用 R2。

处理：

1. 在 Cloudflare 控制台启用 R2
2. 接受计费条款（仍可有免费用量）
3. 重新执行创建存储桶命令

故障：免费套餐上出现插件相关运行时错误

可能原因：残留沙箱配置。

处理：

1. 移除 worker_loaders
2. 关闭依赖沙箱的插件设置
3. 重新部署并复测

回滚策略

采用保守回滚策略：

• 为最后一次已知良好的部署提交打标签
• 若生产出现回退，重新部署该标签对应提交
• 在流量稳定前推迟 schema 或插件变更

在事故窗口内，快速回滚往往优于深挖热修。

何时从免费升级到付费

仅在以下任一成立时升级：

• 需要沙箱化的不可信插件执行
• 流量或存储经常超出免费额度
• 治理要求更强的插件运行时隔离

不要因计费界面措辞含糊而升级；只为明确的能力需求升级。