部署到 Cloudflare

本指南将 EmDash 站点部署到 Cloudflare Workers，使用 D1 作为数据库、R2 作为媒体存储。可从 EmDash Cloudflare 模板开始，或将相同配置应用到现有 Astro 站点。

前提条件

Cloudflare 账户
已安装项目依赖
Wrangler 已通过 Cloudflare 认证（pnpm wrangler login）

配置绑定

Cloudflare 模板包含完整的 Worker 入口点以及命名的 D1 与 R2 绑定。首次部署时，若配置的名称尚不存在，Wrangler 会创建相应资源。请保留 wrangler.jsonc 中的名称；Wrangler 会将后续部署重新连接到相同资源。

模板使用以下绑定：

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-emdash-site",
	"main": "./src/worker.ts",
	"compatibility_date": "2026-02-24",
	"compatibility_flags": ["nodejs_compat"],

	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "my-emdash-site",
		},
	],

	"r2_buckets": [
		{
			"binding": "MEDIA",
			"bucket_name": "my-emdash-media",
		},
	],
	"worker_loaders": [{ "binding": "LOADER" }],
	"triggers": { "crons": ["* * * * *"] },
}

DB、MEDIA 和 LOADER 名称必须与 EmDash 适配器匹配。Cron Trigger 运行计划发布、插件任务、备份与维护。若站点使用沙箱插件，参见 Plugin sandbox。

配置 EmDash

以下 Astro 配置使用 D1 与 R2 绑定。

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import react from "@astrojs/react";
import emdash from "emdash/astro";
import { d1, r2, sandbox } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		react(), // Required — the admin UI is a React app
		emdash({
			database: d1({ binding: "DB" }),
			storage: r2({ binding: "MEDIA" }),
			sandboxRunner: sandbox(),
		}),
	],
});

若站点不使用 marketplace、registry 或 sandboxed 插件，可省略 sandboxRunner 与 LOADER 绑定。

添加 Worker 入口点

Worker 入口点将 Astro 连接到 Cron Trigger，并导出插件桥接：

import handler, { createScheduledHandler, PluginBridge } from "@emdash-cms/cloudflare/worker";

export { PluginBridge };

export default {
	...handler,
	scheduled: createScheduledHandler(),
} satisfies ExportedHandler;

未安装沙箱插件时，PluginBridge 导出会无害。若同一项目稍后可能启用插件，请保留它。

若要在非每分钟的计划上运行常规维护，将同一 Cron 表达式传给 createScheduledHandler({ generalCron: "..." }) 和 triggers.crons。若二者不同，处理函数会记录并忽略意外触发。

构建与部署

构建并部署站点一次，让 Wrangler 配置命名的 D1 数据库与 R2 存储桶。Wrangler 使用 pnpm wrangler login 创建的本地登录。

pnpm build
pnpm wrangler deploy

在默认的 auto 迁移模式下，已部署的 Worker 收到第一个请求时，EmDash 会应用待处理的核心迁移。当部署流水线必须在新代码接收流量之前应用迁移，或需要检查、核对或恢复迁移时，请使用 Manage core database migrations。

若数据库为空（无 collection）且尚未完成配置向导，EmDash 还会在首次启动时应用 seed 文件。Seed 在构建时从 .emdash/seed.json、package.json#emdash.seed 中的路径或 seed/seed.json（以先找到的为准）读取，并内联到包中。若都不存在，则使用内置默认 seed。对已有数据库的后续部署不会改动其内容。

要更改已部署站点的 schema 或内容模型，参见 Evolving a Deployed Site。

将 Worker 放在靠近 D1 的位置

Cloudflare 默认在靠近访客处运行 Worker。EmDash 服务端渲染请求会多次往返 D1，因此请使用 Targeted Placement 在靠近 D1 主库处运行 Worker，以加快这些请求。

Wrangler 接受恰好带有一个选择器的 placement.mode: "targeted"：region、host 或 hostname。选择针对 D1 主库位置的值，并将得到的 placement 对象添加到 wrangler.jsonc。不要与 Targeted Placement 一起启用 D1 只读副本。将 EmDash 的 session 设置保持默认 "disabled"，使读写使用附近的主库。

Object cache

为降低 D1 的读负载，可将内容与配置查询结果缓存在 Cloudflare KV 中。读取从 KV 提供，而不是在每次请求时查询数据库：

import { d1, r2, kvCache } from "@emdash-cms/cloudflare";

emdash({
	database: d1({ binding: "DB" }),
	storage: r2({ binding: "MEDIA" }),
	objectCache: kvCache({ binding: "CACHE" }),
}),

KV 设置、选项与失效行为见 Object Cache。

Workers Cache

Cloudflare 的 Workers Cache 在 Worker 前面放置边缘缓存：匹配的请求会在完全不运行 Worker 的情况下被提供。

启用

使用 Astro 的 Cloudflare 缓存提供程序，使路由规则与 Astro.cache 设置缓存头，并使失效使用 cache.purge()。

import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
 adapter: cloudflare(),
 cache: {
   provider: cacheCloudflare(),
 },
 routeRules: {
   "/": { maxAge: 300, swr: 86400 },
   // Other public routes can use different cache lifetimes.
 },
});

@astrojs/cloudflare 适配器会检测 cacheCloudflare()，并在生成的部署配置中启用 Workers Cache。

使用平台 API 从 Worker 代码清除缓存响应。此调用不需要 Cloudflare REST 凭证。

import { cache } from "cloudflare:workers";

await cache.purge({ purgeEverything: true });
// Or purge selected tags:
await cache.purge({ tags: ["posts"] });

EmDash 管理与 API 响应已发送 Cache-Control: private, no-store，且永不存储。公开页面通过 Cache-Control / routeRules / Astro.cache 控制自身缓存。

启用前须知两点：

没有 Cache-Control 头的响应仍会被缓存。 Workers Cache 应用 RFC 9111 启发式新鲜度——无任何头的 200 会缓存 2 小时。为每个自定义路由给出显式 Cache-Control（对依赖会话的内容使用 private, no-store）。
缓存页面会与已登录编辑者共享。 缓存在 Worker 之前运行，因此无法根据请求 cookie 旁路。已登录编辑者可能收到公开页面的缓存匿名变体——没有可视化编辑工具栏——直到条目过期。编辑者渲染的响应本身永不存储（带有 private, no-store），因此不会向另一方向泄漏。

与 `@emdash-cms/cloudflare` 的 `cloudflareCache()` 不同

	首选：Workers Caching	旧版：`cloudflareCache()`
Config	`"cache": { "enabled": true }` + 来自 `@astrojs/cloudflare/cache` 的 `cacheCloudflare()`	来自 `@emdash-cms/cloudflare` 的 `cache: { provider: cloudflareCache() }`
Storage	Platform Workers Caching	Cache API（`caches.open` / `put` / `match`）
Purge	来自 `cloudflare:workers` 的 `cache.purge()`	Zone REST `POST /zones/{id}/purge_cache`
Secrets	清除无需	`CF_ZONE_ID` + `CF_CACHE_PURGE_TOKEN`

新站点请使用首选路径。仅当已依赖其 Cache API 行为时才保留 cloudflareCache()。

也不要将上述任一与 object cache（objectCache: kvCache({ binding: "CACHE" })）混淆，后者在 KV 中缓存数据库查询结果——是 Worker 下的单独一层。

自定义域名

首次部署会获得 workers.dev URL。自定义域名必须已是与 Worker 同一账户中由 Cloudflare 管理的活动域名。Worker 在其 workers.dev URL 成功响应后，将生产域名添加为 Wrangler 路由：

{
	"routes": [{ "pattern": "www.example.com", "custom_domain": true }],
}

再次部署并验证两个地址。在测试 DNS 时保持 workers.dev 地址可用，有助于区分路由问题与应用问题。

公开 R2 访问

默认情况下，媒体通过 EmDash 的已认证媒体路由提供。若存储桶有公开自定义域名，将该源设为 publicUrl，使生成的媒体 URL 使用它：

storage: r2({
	binding: "MEDIA",
	publicUrl: "https://media.example.com",
}),

公开存储桶访问适用于每个可到达的对象，不仅是媒体。自动 JSON 备份在同一存储后端使用 backups/ 前缀，因此不要通过公开域名暴露该前缀。Choose media storage 说明了安全边界。

图像变换

EmDash 通过 Cloudflare 的 IMAGES 绑定，在 Worker 内调整大小并重新编码 R2 媒体。emdash/ui 的 Image 组件与富文本中的图像都通过 EmDash 在 Cloudflare 适配器下安装的图像端点渲染。对于内部路由 /_emdash/api/media/file/… 上的媒体，该端点直接从 R2 绑定读取源字节，无需 HTTP 获取。这些变换在 Cloudflare Access 之后以及使用 global_fetch_strictly_public 时仍可工作。从存储桶 URL 提供的媒体——见 Public R2 Access——则使用适配器自己的变换端点，该端点在变换前通过 HTTP 获取文件。

你不必声明该绑定。@astrojs/cloudflare 会在 astro build 期间将其添加到生成的 Worker 配置，方式与为 Workers Caching 添加 cache 相同。当运行时图像服务为 cloudflare-binding 时会如此：imageService 未设置、该字符串本身，或 { runtime: "cloudflare-binding" }。其他任何值——"passthrough"、"compile"、"cloudflare"、"custom"——都会省略该绑定。在自己的 wrangler.jsonc 中列出可明确意图：

{
	"images": {
		"binding": "IMAGES",
	},
}

要查看部署实际获得什么，请阅读生成的配置而非 wrangler.jsonc。构建会写入 .wrangler/deploy/config.json，它将 wrangler deploy 指向合并文件（默认 dist/server/wrangler.json）。在那里查找 images 条目。

Cloudflare 将这些变换按 Images transformations 计费。源图像与参数的每个唯一组合每个日历月计费一次，该月内的重复请求免费。若站点有 500 张源图像，且每张请求一个缩略图尺寸和一个主图尺寸，则这两套参数在该月计为 1,000 次变换图像。Images Free 计划每月覆盖 5,000 次唯一变换。超出该限制后，已缓存的变换仍会提供，但新变换会返回 9422 错误，图像请求失败。

Cloudflare Access 认证

Cloudflare Access 可用附加到 Access 应用的身份提供商替换通行密钥认证。受众值是机密运行时设置；通过命名其环境变量将其排除在 astro.config.mjs 之外：

import { access } from "@emdash-cms/cloudflare";

emdash({
	auth: access({
		teamDomain: "myteam.cloudflareaccess.com",
		audienceEnvVar: "CF_ACCESS_AUDIENCE",
		roleMapping: {
			Admins: 50,
			Editors: 40,
		},
	}),
}),

使用 pnpm wrangler secret put CF_ACCESS_AUDIENCE 设置 CF_ACCESS_AUDIENCE。authentication guide 说明用户配置、默认角色与角色同步。

电子邮件

生产 Worker 没有默认电子邮件投递服务。魔法链接登录、团队邀请与评论通知在电子邮件插件激活前会返回 Email is not configured。

Cloudflare 电子邮件插件使用 send_email 绑定。首先通过 Cloudflare Email Sending 接入并验证发件人域名。Cloudflare 会拒绝 From 地址不是已接受发件人的邮件。

添加绑定并注册提供商：

{
	"send_email": [{ "name": "EMAIL" }],
}

import { cloudflareEmail } from "@emdash-cms/cloudflare/plugins";

emdash({
	plugins: [
		cloudflareEmail({
			from: { email: "cms@mails.example.com", name: "My Site CMS" },
			replyTo: "hello@example.com",
		}),
	],
}),

部署后，在 Extensions 下激活插件，并在 Settings → Email 下选择它。在发件人被接受且绑定存在之前，发送会失败。

除非其 binding 选项命名了另一个，否则插件使用名为 EMAIL 的绑定。若它是唯一活动的电子邮件提供商，EmDash 会自动选择它。若有多个提供商活动，请在 Settings → Email 下选择 Cloudflare 提供商。可选的 replyTo 地址在不更改已接受 From 地址的情况下接收回复。插件可为单条消息设置 replyTo，从而覆盖该消息的此选项。

Cloudflare AI Search

AI Search 插件需要原生插件注册与 ai_search_namespaces 绑定。部署后，在管理中打开 Cloudflare AI Search，选择 collection，并运行 Sync All Content。初始同步会索引启用插件之前发布的内容；hooks 会保持后续更改同步。

import { aiSearch } from "@emdash-cms/cloudflare/plugins";

emdash({
	plugins: [aiSearch()],
}),

{
	"ai_search_namespaces": [{ "binding": "AI_SEARCH", "namespace": "default" }],
}

从站点暴露搜索路由：

export { POST, prerender } from "@emdash-cms/cloudflare/plugins/ai-search";

将搜索界面添加到布局。触发插槽接受与站点设计匹配的按钮：

---
import AISearchSnippet from "@emdash-cms/cloudflare/plugins/ai-search/astro";
---

<AISearchSnippet apiUrl="/api/ai-search" placeholder="Search content">
	<button slot="trigger" type="button">Search</button>
</AISearchSnippet>

Worker 密钥

使用 pnpm wrangler secret put <NAME> 存储密钥值。不要将它们放入 wrangler.jsonc，也不要从构建时的 import.meta.env 值读取。

EMDASH_ENCRYPTION_KEY 加密声明为密钥的插件设置。在保存插件密钥之前设置它，并与 D1 备份分开保存。轮换期间，先提供新密钥，并在逗号后保留较旧密钥，直到每个插件密钥再次保存。Secrets and key management 描述轮换与恢复。

插件桥直接读取此 Worker 密钥绑定。生成的管理设置路由通过 process.env 读取它。使用 nodejs_compat 时，Cloudflare 对兼容日期 2025-04-01 及之后默认填充 process.env。固定到更早日期的项目在保存加密设置之前还必须添加 nodejs_compat_populate_process_env。

EmDash 在运行时从 process.env 读取密钥。Worker 代码从 cloudflare:workers 导入的 env 读取绑定。切勿通过 import.meta.env 读取密钥：Vite 在构建时替换这些值，并可能将它们写入服务器包。

预览 HMAC 密钥与评论者 IP 盐除非你提供运行时覆盖，否则会生成并存储在数据库中。Secrets and key management 列出确切变量、存储位置与轮换效果。

预览部署

命名的 Wrangler 环境不继承绑定。创建单独的预览资源，并在构建前写入 preview 环境：

pnpm wrangler d1 create my-emdash-site-preview \
  --binding DB --env preview --update-config
pnpm wrangler r2 bucket create my-emdash-media-preview \
  --binding MEDIA --env preview --update-config

预览环境必须重复预览 Worker 使用的每个绑定。在 Wrangler 写入资源标识符后，核心 D1、R2 与沙箱绑定具有以下形状：

{
	"env": {
		"preview": {
			"d1_databases": [
				{
					"binding": "DB",
					"database_name": "my-emdash-site-preview",
					"database_id": "00000000-0000-0000-0000-000000000000",
				},
			],
			"r2_buckets": [
				{
					"binding": "MEDIA",
					"bucket_name": "my-emdash-media-preview",
				},
			],
			"worker_loaders": [{ "binding": "LOADER" }],
		},
	},
}

使用 Wrangler 写入的预览 UUID。当预览使用这些功能时，重复可选的 KV、AI Search、电子邮件及其他绑定。使用 pnpm wrangler secret put <NAME> --env preview 添加仅预览密钥。

构建并部署预览环境。其第一个请求通过默认 auto 模式应用待处理的核心迁移。

pnpm build
pnpm wrangler deploy --env preview

在分享之前验证预览 URL、管理登录、媒体上传以及任何可选绑定。切勿将预览绑定指向生产数据库或存储桶。

验证部署

部署后，请求一个公开页面，登录 /_emdash/admin，上传并检索测试媒体文件，并确认计划处理函数出现在 pnpm wrangler tail 中。

故障排除

「D1 binding not found」

验证 wrangler.jsonc 中的绑定名称与数据库配置匹配：

// Must match: d1({ binding: "DB" })
"binding": "DB"

「R2 binding not found」

检查 R2 存储桶是否正确绑定：

// Must match: r2({ binding: "MEDIA" })
"binding": "MEDIA"

迁移错误

若看到 schema 错误，跟踪 Worker 日志（wrangler tail）并复现错误以捕获底层消息——然后带着该输出提交 issue。