基于 Cloudflare Workers 与 Durable Objects 搭建 tldraw 实时多人同步后端(sync-cloudflare 模板全解析)

原创2026-09-09 22:35:331,739 阅读
文章标签:前端UI组件WebSocket富文本协同办公

基于 Cloudflare Workers 与 Durable Objects 搭建 tldraw 实时多人同步后端(sync-cloudflare 模板全解析)

导读

本篇文章以仓库中 templates/sync-cloudflare 模板为核心,完整讲解如何基于 Cloudflare Workers、Durable Objects 与 R2 对象存储,为 tldraw 应用搭建一套生产可用的实时多人协作后端。这套模板是 www.tldraw.com 线上多人协作系统的最小化复刻:每个白板房间由一个独立的 Durable Object 承载,通过 WebSocket 实时同步绘图数据,并借助 R2 存储图片/视频等静态资产,还附带书签链接预览的抓取能力。读完本文你将掌握:tldraw 同步后端的整体架构与数据流、Worker 路由与 Durable Object 的关键实现、客户端如何通过 useSync 与 TLAssetStore 接入多人协作、如何把整套系统迁移到自己的仓库并部署到 Cloudflare。

1. 模板概览:一次搞清 tldraw sync 后端的构成

templates/sync-cloudflare 是一个"生产就绪(production-ready)"的 tldraw 同步后端模板。它的核心设计思想是:前端应用可以托管在任何地方,后端则完全构建在 Cloudflare 云产品之上。从 README.md 可以提炼出以下关键事实:

  • 后端基于 Cloudflare Workers,需要部署到你自己的 Cloudflare 账户中;
  • 每个白板房间通过 WebSocket 连接到一个 Cloudflare Durable Object,房间状态持久化在该 Durable Object 内置的 SQLite 存储中;
  • 上传的图片与视频存放在 Cloudflare R2 存储桶中;
  • 除同步外,服务器还包含一个与 tldraw 同步无关的附加组件:为画布中粘贴的 URL 抓取链接预览(bookmark unfurling)。

这套系统正是 www.tldraw.com 线上多人协作所使用系统的最小化版本。其扩展性的关键在于 Durable Objects 的架构特性:每个活跃房间都会隐式地创建一台"迷你服务器"实例,因此官方无需担心规模问题——Cloudflare 负责保证每个房间只有一个实例,并确保所有用户都能连接到该实例。根据模板 README 的描述,在这种方案下每个房间大约可以承载 50 位同时协作者。

1.1 目录结构速览

模板的源码结构非常清晰,后端与前端分离:

templates/sync-cloudflare/
├── worker/
│   ├── worker.ts                    # Worker 主入口,定义所有路由
│   ├── TldrawDurableObject.ts       # 同步 Durable Object,每个房间一个实例
│   └── assetUploads.ts              # 静态资产(图片/视频)的上传、下载与缓存
├── client/
│   ├── main.tsx                     # 前端入口,react-router 路由
│   ├── multiplayerAssetStore.tsx    # 客户端资产上传/获取的 TLAssetStore 实现
│   ├── getBookmarkPreview.tsx       # 客户端书签预览获取逻辑
│   └── pages/
│       ├── Root.tsx                 # 根路由,生成/跳转房间 ID
│       └── Room.tsx                 # 房间页面,接入 useSync 与 Tldraw 组件
├── wrangler.toml                    # Cloudflare 部署配置
├── package.json                     # 依赖与脚本
├── vite.config.ts                   # Vite + Cloudflare Vite 插件配置
└── arch.png                         # 架构示意图

2. 架构与数据流:每个房间一台"迷你服务器"

模板 README 中给出了架构图(arch.png),直观展示了系统两条核心数据通路:房间同步(room sync)与图片/视频资产(image/video assets)。

tldraw sync-cloudflare 模板架构图:浏览器经 Cloudflare 边缘 Worker 连接到各自房间的 Durable Object,静态资产走 R2 存储桶

2.1 房间同步通路

当用户打开一个房间时,完整的数据流是这样的:

  1. 连接:浏览器客户端通过 Workers 连接到对应房间的 Durable Object。每个 Durable Object 就像一台独立的迷你服务器,每个房间只有一个,且该房间的所有用户都连接到它;
  2. 变更广播:用户对画布做出修改后,修改内容经由 WebSocket 连接发送给该房间的 Durable Object;
  3. 应用与同步:Durable Object 将变更应用到它内存中的文档副本,并通过 WebSocket 把变更广播给房间内的所有其他已连接客户端;
  4. 自动持久化:房间状态会自动持久化到 Durable Object 内置的 SQLite 存储中,因此可以安然度过重启与休眠(hibernation)周期;
  5. 销毁:当最后一个客户端离开房间时,该 Durable Object 会自行关闭。

2.2 资产通路

图片和视频这类静态资产体积太大,不适合通过 WebSocket 与 Durable Object 同步。因此:

  • 上传:资产被上传到 Worker,由 Worker 存入 R2 存储桶;
  • 下载与缓存:资产下载时会在 Cloudflare 边缘网络(edge network)上缓存,既降低了成本,也加快了服务速度。

2.3 规模化的秘密

这套架构之所以"不用操心扩展",根源在于 Durable Objects 的语义:每个房间有且仅有一个实例(由 idFromName(roomId) 确定性派生),所有用户都连向同一个实例,天然的按房间隔离意味着并发房间再多也只是"多部署几台迷你服务器"的问题。Cloudflare 接管了"每个房间只有一个实例"以及"让每个用户都连到该实例"的底层基础设施工作。

3. Worker 主入口:路由与房间寻址

后端入口位于 worker/worker.ts,它使用 itty-router 做路由分发,并导出了同步 Durable Object 供 Cloudflare 注册:

export { TldrawDurableObject } from './TldrawDurableObject'

const router = AutoRouter<IRequest, [env: Env, ctx: ExecutionContext]>({
	catch: (e) => {
		console.error(e)
		return error(e)
	},
})
	// 请求 /connect 会被路由到 Durable Object,处理实时 WebSocket 同步
	.get('/api/connect/:roomId', (request, env) => {
		const id = env.TLDRAW_DURABLE_OBJECT.idFromName(request.params.roomId)
		const room = env.TLDRAW_DURABLE_OBJECT.get(id)
		return room.fetch(request.url, { headers: request.headers, body: request.body })
	})
	// 资产可以上传到 /uploads 路径下的存储桶
	.post('/api/uploads/:uploadId', handleAssetUpload)
	// 也可以从存储桶取回
	.get('/api/uploads/:uploadId', handleAssetDownload)
	// 书签需要从粘贴的 URL 中提取元数据
	.get('/api/unfurl', handleUnfurlRequest)
	.all('*', () => {
		return new Response('Not found', { status: 404 })
	})

export default {
	fetch: router.fetch,
}

关键点逐一拆解:

  • /api/connect/:roomId:同步连接的入口。env.TLDRAW_DURABLE_OBJECT.idFromName(roomId) 根据房间名确定性生成 Durable Object ID——同一房间名永远解析到同一实例,这正是"每个房间一台服务器"的基石。随后把请求原样转发给该 Durable Object 的 fetch。
  • /api/uploads/:uploadId:资产的 POST(上传)与 GET(下载)路由,具体逻辑在 worker/assetUploads.ts。
  • /api/unfurl:书签链接预览,由 cloudflare-workers-unfurl 包的 handleUnfurlRequest 实现。
  • 模板默认开启 CORS(因为 Worker 与客户端是分开托管的),README 明确提醒:生产环境应把 CORS 限制为你自己的域名。

4. TldrawDurableObject:房间同步的核心实现

worker/TldrawDurableObject.ts 是整套系统的"心脏"。它的职责是用 TLSocketRoom(来自 @tldraw/sync-core 包)对外暴露一个 WebSocket 房间,并把房间状态持久化到 Durable Object 内置的 SQLite 存储。

4.1 房间的创建:内存态 + SQLite 持久化

房间实例按需懒创建,创建时完成 schema 配置、存储层装配与事件回调注册:

private getOrCreateRoom(): TLSocketRoom<TLRecord, void> {
	if (!this.room) {
		const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage)
		const storage = new SQLiteSyncStorage<TLRecord>({ sql })

		this.room = new TLSocketRoom<TLRecord, void>({
			schema,
			storage,
			// 关闭空闲超时:Cloudflare 通过自动应答维持心跳
			clientTimeout: Infinity,
			onSessionSnapshot: (sessionId, snapshot) => {
				const ws = this.sessionIdToWs.get(sessionId)
				if (ws) ws.serializeAttachment({ sessionId, snapshot })
			},
		})
		// 恢复休眠前幸存的会话
		for (const ws of this.ctx.getWebSockets()) {
			const attachment = getAttachment(ws)
			if (!attachment?.snapshot) continue
			this.room.handleSocketResume({
				sessionId: attachment.sessionId,
				socket: ws,
				snapshot: attachment.snapshot,
			})
		}
	}
	return this.room
}
  • 存储:DurableObjectSqliteSyncWrapper 把 Durable Object 的 ctx.storage 包装成 SQLite 接口,SQLiteSyncStorage 则是 tldraw 的 TLSocketRoom 需要的持久化实现。房间状态因此自动写入 DO 的 SQLite 存储,在重启与休眠后仍然存活。
  • clientTimeout: Infinity:这是一个精妙的细节。Cloudflare 在平台层用自动应答处理 keep-alive,所以如果保留默认的超时逻辑,会话会在 20 秒无"真实"消息后被误判为离线剪除——即便客户端其实一直在线并被自动 pong。因此这里显式禁用超时。
  • 休眠恢复:DO 休眠期间 WebSocket 由 Cloudflare 平台层保活;DO 被唤醒后,通过 ctx.getWebSockets() 取回存活的连接,用 attachment 中保存的 snapshot 调用 handleSocketResume 恢复会话。

4.2 WebSocket 握手与 Hibernation API

构造函数里有一处关键配置——平台级 ping 自动应答:

constructor(ctx: DurableObjectState, env: Env) {
	super(ctx, env)
	// TLSyncClient 每 5 秒发送 {"type":"ping"};若不处理,每次 ping 都会把 DO 从休眠中唤醒
	this.ctx.setWebSocketAutoResponse(
		new WebSocketRequestResponsePair('{"type":"ping"}', '{"type":"pong"}')
	)
}

tldraw 客户端(TLSyncClient)每 5 秒发送一次 {"type":"ping"}。setWebSocketAutoResponse 让 Cloudflare 在平台层直接回 pong,DO 实例根本不会被唤醒,从而显著降低休眠场景下的资源开销。

handleConnect 处理新的 WebSocket 连接请求:

async handleConnect(request: IRequest) {
	const sessionId = request.query.sessionId as string
	if (!sessionId) return error(400, 'Missing sessionId')

	const { 0: clientWebSocket, 1: serverWebSocket } = new WebSocketPair()
	// 使用休眠 API 而非 serverWebSocket.accept()
	this.ctx.acceptWebSocket(serverWebSocket)

	const attachment: SocketAttachment = { sessionId, snapshot: null }
	serverWebSocket.serializeAttachment(attachment)

	this.getOrCreateRoom().handleSocketConnect({ sessionId, socket: serverWebSocket })

	return new Response(null, { status: 101, webSocket: clientWebSocket })
}

要点:

  • 必须校验 sessionId 查询参数,缺失时返回 400;
  • 采用 WebSocket Hibernation API:用 ctx.acceptWebSocket(serverWebSocket) 替代手动 accept(),连接不活跃时 DO 可以休眠;
  • 在握手完成前就把 sessionId 写入 socket attachment,确保 DO 休眠恢复后仍能识别每个 socket;
  • 客户端收到的 101 Switching Protocols 响应通过 webSocket: clientWebSocket 返回。

消息、关闭、错误三个生命周期钩子都做了适配:webSocketMessage 中用 sessionIdToWs 映射记录当前 socket(供 onSessionSnapshot 序列化快照回写),并把消息交给房间处理;webSocketClose / webSocketError 则统一走 handleWebSocketEnd——其中还有一个优雅的细节:如果 DO 此前在休眠,断开的会话从未被重新加入房间(ctx.getWebSockets() 不包含正在断开的 socket),则先短暂 handleSocketResume 恢复它,让房间能向其他客户端广播 presence 移除,再执行 handleSocketClose / handleSocketError。

4.3 Schema:自定义形状的扩展点

TldrawDurableObject.ts 顶部用 createTLSchema 构造同步 schema:

const schema = createTLSchema({
	shapes: { ...defaultShapeSchemas },
	// bindings: { ...defaultBindingSchemas },
})

默认只启用 tldraw 的内置形状 schema,注释中预留了自定义形状与绑定(bindings)的扩展点。README 也提示:要支持自定义形状,参见 tldraw 官方 sync 文档中的 "Custom shapes & bindings" 章节。

5. 资产上传与下载:R2 + 边缘缓存的完整实现

worker/assetUploads.ts 实现了图片/视频等静态资产的上传、下载与缓存,共三个关键函数。

5.1 上传(handleAssetUpload)

export async function handleAssetUpload(request: IRequest, env: Env) {
	const objectName = getAssetObjectName(request.params.uploadId)
	const contentType = request.headers.get('content-type') ?? ''
	if (!contentType.startsWith('image/') && !contentType.startsWith('video/')) {
		return error(400, 'Invalid content type')
	}
	if (await env.TLDRAW_BUCKET.head(objectName)) {
		return error(409, 'Upload already exists')
	}
	await env.TLDRAW_BUCKET.put(objectName, request.body, {
		httpMetadata: request.headers,
	})
	return { ok: true }
}

安全与幂等细节:只允许 image/* 与 video/* 类型(其余返回 400);用 head 检查同名对象是否已存在,存在则返回 409 防止重复上传;对象名统一经过 getAssetObjectName 清洗——uploadId.replace(/[^a-zA-Z0-9_-]+/g, '_') 确保只保留安全字符,防止路径穿越。

5.2 下载与缓存(handleAssetDownload)

下载逻辑展示了生产级缓存策略:

export async function handleAssetDownload(request: IRequest, env: Env, ctx: ExecutionContext) {
	const objectName = getAssetObjectName(request.params.uploadId)

	// 命中缓存直接返回(自动处理 Range 等请求头)
	const cacheKey = new Request(request.url, { headers: request.headers })
	const cachedResponse = await caches.default.match(cacheKey)
	if (cachedResponse) return cachedResponse

	// 未命中则从存储桶取回,支持 Range 请求
	const object = await env.TLDRAW_BUCKET.get(objectName, {
		range: request.headers,
		onlyIf: request.headers,
	})
	if (!object) return error(404)

	const headers = new Headers()
	object.writeHttpMetadata(headers)

	// 资产不可变,几乎可以永久缓存
	headers.set('cache-control', 'public, max-age=31536000, immutable')
	headers.set('etag', object.httpEtag)

	// 允许所有客户端访问;在这里设置 CORS,避免缓存响应再被追加 CORS 头(Cloudflare 不允许)
	headers.set('access-control-allow-origin', '*')

	// 防止用户上传的 SVG 等可执行类型造成 XSS
	headers.set('content-security-policy', "default-src 'none'")
	headers.set('x-content-type-options', 'nosniff')
	// ...(content-range 计算略,见源码)

值得注意的工程细节:

  • 不可变缓存:资产对象名带唯一 ID,内容一旦写入不再变更,因此 cache-control 设为 public, max-age=31536000, immutable(一年);
  • Range 支持:透传 range / onlyIf 请求头到 R2,并手动计算 content-range(Cloudflare 的 writeHttpMetadata 不会自动写该头),实现视频拖动进度等场景的字节范围请求,状态码相应为 206;
  • 缓存写入:只缓存完整的 200 响应,用 body.tee() 分流,通过 ctx.waitUntil 异步写入 caches.default,不阻塞用户响应;
  • 安全响应头:content-security-policy: default-src 'none' 与 x-content-type-options: nosniff 用于防御用户上传 SVG 等可执行内容引发的 XSS;
  • 缓存键:使用包含请求头的完整 Request 作为缓存键,确保 Range 语义正确。

6. 客户端接入:从 useSync 到 TLAssetStore

前端入口在 client/main.tsx,用 react-router 定义两条路由:/ 交给 Root,/:roomId 交给 Room。client/pages/Root.tsx 会在本地存储(localStorage)里记住一个房间 ID,不存在则用 uniqueId() 生成,然后重定向到该房间。

6.1 房间页:useSync 连接实时协作

client/pages/Room.tsx 是核心:

export function Room() {
	const { roomId } = useParams<{ roomId: string }>()

	// 创建一个连接到多人服务器的 store
	const store = useSync({
		// 我们需要知道 WebSocket 地址...
		uri: `${window.location.origin}/api/connect/${roomId}`,
		// ...以及如何处理图片、视频等静态资产
		assets: multiplayerAssetStore,
	})

	return (
		<RoomWrapper roomId={roomId}>
			<Tldraw
				store={store}
				options={{ deepLinks: true }}
				onMount={(editor) => {
					// 编辑器就绪后,注册书签链接预览服务
					editor.registerExternalAssetHandler('url', getBookmarkPreview)
				}}
			/>
		</RoomWrapper>
	)
}
  • useSync 来自 @tldraw/sync 包,负责建立并维护与 /api/connect/:roomId 的 WebSocket 连接,返回一个已连接多人服务器的 store;
  • 把 store 传给 <Tldraw store={store}> 后,组件会自动处理加载状态,并启用多人游标、presence 菜单等多人 UX;
  • options={{ deepLinks: true }} 让编辑器支持深链(deep link)导航;
  • onMount 中通过 editor.registerExternalAssetHandler('url', getBookmarkPreview) 注册外部 URL 资产处理器,把画布中粘贴的链接转成带预览的书签形状。

RoomWrapper 还提供了房间页顶栏:显示当前 roomId、提供复制房间链接按钮(复制成功短暂显示 "Copied!")。

6.2 资产存取:multiplayerAssetStore

client/multiplayerAssetStore.tsx 实现了 tldraw 的 TLAssetStore 接口,回答"客户端如何向 Worker 上传、取回资产":

export const multiplayerAssetStore: TLAssetStore = {
	async upload(_asset, file) {
		// 生成唯一对象名与 URL
		const objectName = `${uniqueId()}-${file.name}`.replace(/[^a-zA-Z0-9.]/g, '-')
		const url = `/api/uploads/${objectName}`
		// POST 给 Worker 完成上传
		const response = await fetch(url, { method: 'POST', body: file })
		if (!response.ok) {
			throw new Error(`Failed to upload asset: ${response.statusText}`)
		}
		// 返回 URL,随资产记录一并存储
		return { src: url }
	},
	resolve(asset) {
		// 取回资产直接用同一 URL
		return asset.props.src
	},
}

upload 用 uniqueId() 拼出唯一的对象名并 POST 到 /api/uploads/{name},成功后把 URL 存进资产记录;resolve 直接返回该 URL 作为下载地址。模板注释也提示:resolve 是定制鉴权、或按需返回优化尺寸/版本的理想接入点。

6.3 书签预览:getBookmarkPreview

client/getBookmarkPreview.tsx 实现客户端一侧的书签 unfurling:

export async function getBookmarkPreview({ url }: { url: string }): Promise<TLAsset> {
	// 先用空资产记录占位
	const asset: TLBookmarkAsset = {
		id: AssetRecordType.createId(getHashForString(url)),
		typeName: 'asset',
		type: 'bookmark',
		meta: {},
		props: { src: url, description: '', image: '', favicon: '', title: '' },
	}
	try {
		// 向服务器请求预览数据
		const response = await fetch(`/api/unfurl?url=${encodeURIComponent(url)}`)
		const data: any = await response.json()
		asset.props.description = data?.description ?? ''
		asset.props.image = data?.image ?? ''
		asset.props.favicon = data?.favicon ?? ''
		asset.props.title = data?.title ?? ''
		// 把社交图尺寸放到 meta 上,让嵌入内容(如 Vimeo/YouTube)按真实宽高比排版
		if (typeof data?.imageWidth === 'number') asset.meta.imageWidth = data.imageWidth
		if (typeof data?.imageHeight === 'number') asset.meta.imageHeight = data.imageHeight
	} catch (e) {
		console.error(e)
	}
	return asset
}

细节:用 getHashForString(url) 派生确定性资产 ID;元数据(标题、描述、图片、favicon)缺失时优雅回退为空字符串;尤其贴心的是把社交预览图的宽高写入 meta,让 Vimeo/YouTube 这类嵌入形状能按内容的真实宽高比排版,而不是被 letterbox 留黑边。

7. 部署配置:wrangler.toml 逐项解读

模板根目录的 wrangler.toml 是 Cloudflare 侧的完整配置:

name = "multiplayer-template"
main = "worker/worker.ts"
compatibility_date = "2025-05-08"
compatibility_flags = ["nodejs_compat"]
upload_source_maps = true
preview_urls = true

[[routes]]
pattern = "multiplayer.templates.tldraw.dev"
custom_domain = true

[observability]
enabled = true

[assets]
not_found_handling = "single-page-application"
directory = "./dist/client"

# 为每个 tldraw 房间设置的 Durable Object
[durable_objects]
bindings = [{ name = "TLDRAW_DURABLE_OBJECT", class_name = "TldrawDurableObject" }]

# Durable Objects 需要 migration 来创建/修改/删除
# 使用 new_sqlite_classes 以启用 SQLite 存储
[[migrations]]
tag = "v1"
new_sqlite_classes = ["TldrawDurableObject"]

# 资产上传(图片、视频)存放在 R2 存储桶中
[[r2_buckets]]
binding = 'TLDRAW_BUCKET'
bucket_name = 'multiplayer-template'
preview_bucket_name = 'multiplayer-template-preview'

逐项说明:

  • main = "worker/worker.ts":Worker 入口文件,即上文解析的路由主入口;
  • compatibility_date 与 compatibility_flags:指定 Cloudflare Workers 兼容性日期与 nodejs_compat 标志(node 兼容 API 需要);
  • [assets]:把 ./dist/client 构建产物作为静态资源托管,not_found_handling = "single-page-application" 让未知路径回退到前端 SPA 入口——前端与后端一次部署、同域同源,因此客户端里的 /api/... 相对路径可以直接命中 Worker 路由;
  • [durable_objects]:注册 TLDRAW_DURABLE_OBJECT 绑定,映射到 TldrawDurableObject 类,供 Worker 中 env.TLDRAW_DURABLE_OBJECT.idFromName(...) 使用;
  • [[migrations]]:Durable Object 必须通过 migration 创建/修改/删除,这里用 new_sqlite_classes 声明 SQLite 支持的类(tag v1);
  • [[r2_buckets]]:绑定 TLDRAW_BUCKET 到指定 R2 桶,含 preview 桶。

依赖方面,package.json 中关键依赖为:@tldraw/sync(客户端 useSync)、@tldraw/sync-core(服务端 TLSocketRoom)、@tldraw/tlschema(schema 构造)、cloudflare-workers-unfurl(链接预览)、itty-router(路由)、wrangler 与 @cloudflare/vite-plugin(本地开发与部署)。开发脚本为 dev(vite --host)、build(tsc && vite build)、preview(vite preview)。

8. 开发与部署:从本地跑起来到上线

8.1 本地开发

按 README.md 的说明,两步即可启动:

yarn        # 安装依赖
yarn dev    # 启动本地开发服务器

yarn dev 会启动一个 Vite 开发服务器,同时运行你的应用前端与 Cloudflare Workers 后端——后端通过 Cloudflare 官方 Vite 插件(@cloudflare/vite-plugin)加载。随后访问 http://localhost:5137 即可看到应用与服务器同时运行。

8.2 部署到 Cloudflare

部署前需要准备:

  1. 注册一个 Cloudflare 账户;
  2. 创建一个 R2 存储桶用于存放上传的图片与视频;
  3. 把 wrangler.toml 中的 bucket_name = 'multiplayer-template' 改成你自己桶的名字(README 中示例为 tldraw-content)。

然后执行:

yarn build          # 先构建生产版本
yarn wrangler deploy  # 部署后端 Worker 与前端应用

部署完成后会得到一个 *.workers.dev 的 URL;当然你也可以在 Cloudflare 控制台配置自定义域名(模板本身已在 [[routes]] 中声明了 multiplayer.templates.tldraw.dev 的自定义域名示例)。

9. 迁移到自己仓库:把服务器与客户端接入现有应用

如果你已经有一个基于 tldraw 的应用,想复用这套系统,README 给出了清晰的搬运指南。

9.1 后端部分

  1. 把 worker/ 文件夹的全部内容复制到你的应用中;
  2. 复制根目录的 wrangler.toml;
  3. 从 package.json 中把对应依赖加入你的项目;
  4. 在 wrangler.toml 所在目录运行 wrangler dev 即可本地启动 Worker。

9.2 前端部分

  1. 复制 client/multiplayerAssetStore.tsx 与 client/getBookmarkPreview.tsx 到你的应用中;
  2. 参照 client/pages/Room.tsx 中的写法,把 useSync + <Tldraw store={store}> 的接入代码适配到你自己的应用;
  3. 修改上述文件中用到的 /api/ 前缀 URL,指向你新启动的 wrangler dev 服务器地址。

若你的应用需要自定义形状(custom shapes),除在服务端 TldrawDurableObject.ts 的 createTLSchema 中注册外,还需要在客户端同步相同的 schema 定义(详见官方 sync 文档的 "Custom shapes & bindings" 章节)。

10. 关键配置速查表

配置项 位置 说明
同步路由 /api/connect/:roomId worker/worker.ts WebSocket 连接入口,按房间名寻址 Durable Object
资产上传/下载 /api/uploads/:uploadId worker/worker.ts R2 资产的 POST/GET 路由
书签预览 /api/unfurl worker/worker.ts URL 元数据抓取
Durable Object 绑定 wrangler.toml TLDRAW_DURABLE_OBJECT → TldrawDurableObject
SQLite 迁移 wrangler.toml new_sqlite_classes = ["TldrawDurableObject"]
R2 桶绑定 wrangler.toml TLDRAW_BUCKET,部署前需改名
客户端多人接入 client/pages/Room.tsx useSync + store 传入 <Tldraw>
客户端资产存取 client/multiplayerAssetStore.tsx 实现 TLAssetStore 接口
客户端书签预览 client/getBookmarkPreview.tsx registerExternalAssetHandler('url', ...) 注册

11. 总结与下一步

这套 sync-cloudflare 模板展示了一条清晰的路径:用 Cloudflare Workers + Durable Objects + R2 三件套,在云原生边缘平台上跑起 tldraw 实时多人协作。其核心工程智慧在于——利用 Durable Objects"每个房间一个确定性实例"的语义自动获得水平扩展能力,用 SQLite 内置存储免去额外数据库运维,用边缘缓存与平台级心跳应答把成本与延迟压到最低。

如果你打算在生产环境使用,建议重点关注三处自定义:一是将 Worker 的 CORS 收窄到自己的域名;二是按业务需求改造 multiplayerAssetStore 的 resolve(鉴权、压缩版本);三是在 createTLSchema 中注册你自定义的形状与绑定 schema。模板中的 worker/TldrawDurableObject.ts、worker/assetUploads.ts 与 client/pages/Room.tsx 是理解整套系统的最佳起点,配合 wrangler.toml 即可在数分钟内把一套可扩展的 tldraw 多人协作后端跑起来。

登录后查看全文
tldraw