进阶 celld.dev 2026-10-11 10:08:47 · 53 阅读

第1章 celld 的 Cloudflare 兼容性指南

文档Cloudflare 兼容性

本页只列出与对应 Cloudflare API 的差异。没有备注的条目即与 Cloudflare 行为一致。

Yes:已实现,除列出的差异外。 Partial:相当一部分功能不可用。 Experimental:可能随时变更。 No:未实现。

celld 在部署时或首次使用时就拒绝不支持的配置或 API。 不报错的未支持功能属于缺陷。

服务

| 服务 | 状态 | |---|---| | Workers | Yes | | Durable Objects | Yes | | Durable Object Facets | Yes | | Containers | Experimental | | Static assets | Yes | | Cron Triggers | Yes | | Dynamic Workers | Yes | | KV | Yes | | Queues | Yes | | D1 | Yes | | Workflows | Yes | | R2 | Yes | | Workers AI | No | | Vectorize | No | | Hyperdrive | No | | Browser Rendering | No | | Email Workers | No | | Python Workers | Partial — 仅限 Pyodide 0.28 运行时线上的 fetch 处理器 |

运行时 API

| API | 状态 | |---|---| | Fetch, Request, Response, and Headers | Yes | | Bindings | Yes | | Context | Yes | | Handlers | Yes | | RPC | Yes | | Streams | Yes | | Encoding | Yes | | WebSockets | Yes | | Web Crypto | Yes | | Web standards | Yes | | WebAssembly | Yes | | Performance and timers | Yes | | Console | Yes | | Node.js compatibility | Partial | | Cache | Partial | | HTMLRewriter | Yes | | TCP sockets | Yes | | EventSource | Yes | | MessageChannel | Yes | | BroadcastChannel | No |

Fetch, Request, Response, and Headers

请求的 cache 选项不可用。 入站 Request 的 cf 对象不含 Cloudflare 边缘节点字段。celld 无法证明地理位置、colo 或 TLS 元数据。 除 HEAD 响应外,celld 会从 Worker 响应中移除 Content-Length。 远程 Durable Object 调用一旦开始传输请求体就无法重试,因为 celld 不保存重放副本。 远程 Durable Object 调用等待被拒绝的 owner generation 变更的时间不超过 CELLD_OPERATION_DEADLINE_MS。

Bindings

只有服务表中列出的绑定类型可用。

Context

passThroughOnException() 无效,因为 celld 没有 CDN 回退。 ctx.facets 仅在 Durable Object 内部可用。

Handlers

tail 和 email 处理器不可用。

RPC

RPC stub 不能跨 isolate 边界。 Durable Object RPC 调用中的 AbortSignal 不能跨节点边界。 只有当失败的对端尝试尚未开始执行方法时才会重试远程 RPC。应用层重试请使用稳定的操作 ID。

Streams

celld 会在 60 秒后使未认领且不活跃的 HTTP 流过期。流操作成功会开启新的 60 秒周期。 已过期或未知的流会报错而非返回 EOF。

WebSockets

出站 Worker socket 在其事件和 waitUntil 工作结束后关闭。响应中返回的 socket 则保持打开。 每个 isolate 轮询的输入队列对非终结帧有 1 MiB 的预算。超过 1 MiB 的消息会占满整个预算。 如果 isolate 停止轮询,celld 会在清理时丢弃未读帧。后续 pull 会报告异常关闭。 WebSocket 传输无法迁移到新的 cell owner。客户端必须使用同一应用操作 ID 重连。 隧道连接会原样转发 owner 的 Close 帧,不再额外发送 Close。如果 owner 连接在帧之间、Close 之前失败,ingress 会发送代码 1012。如果帧不完整,ingress 则直接关闭传输。 acceptWebSocket() 在超过 V8 堆上限 90% 时抛出异常。 对不带 Upgrade: websocket 的请求返回含 WebSocket 的响应会失败,与 workerd 相同。此时 Durable Object 的 stub.fetch() 调用会拒绝,HTTP 客户端收到状态码 500,socket 的服务端则收到代码 1006 的 close 事件。 无论在 owner 节点还是其他节点上,处理器失败时 Durable Object 的 stub.fetch() 调用都会拒绝。

Web Crypto

HMAC 接受 MD5、SHA-1、SHA-224、SHA-256、SHA-384 和 SHA-512。 ECDSA 仅支持 P-256 曲线配合 SHA-256。 AES-GCM 接受 96 到 128 位、以 8 位为步长的认证标签。 RSA-OAEP 接受 SHA-1、SHA-256、SHA-384 和 SHA-512。非空 label 必须是有效 UTF-8。 私钥不能在 exportKey() 或 wrapKey() 中使用 jwk。 Ed25519 支持签名和验证,NODE-ED25519 指同一算法。一种写法生成的签名可在另一种写法下验证。 X25519 支持派生位串和密钥。低阶对端密钥会产生全零共享密钥,因此 deriveBits() 会拒绝该密钥。 Ed25519 或 X25519 公钥的 raw 格式使用其 32 字节点,所以 importKey() 和 exportKey() 都只承载该点本身。

Web standards

Performance and timers

performance.timeOrigin 为 0,performance.now() 与 Date.now() 一致。 两个时钟在 I/O 边界推进,在 JavaScript 执行期间保持不变。

Node.js compatibility

celld 实现了 node:assert、node:async_hooks、node:buffer、node:diagnostics_channel、node:events、node:fs、node:os、node:path、node:stream、node:timers/promises 和 node:util。 node:diagnostics_channel 不能向 tail Worker 导出消息。 node:crypto 不实现 Diffie-Hellman、流式签名、密码、RSA-PSS 或 DSA 签名与密钥生成。 KeyObject.toCryptoKey() 会将所请求的算法、可导出性和用途应用到非对称密钥上。 node:zlib 仅实现同步的 gzip 和 deflate 函数。 node:fs 提供 access、mkdir、realpath、stat、lstat 和 readFile。它暴露一个空的、请求本地的 /tmp,以及一个只读的 /bundle(包含 Worker 模块)。 全局 process 在 workerd 定义的每个字段上都与其一致,如 process.execPath、process.argv 和 process.title。其他字段,如 process.kill 和 process.features,为 undefined。 celld 打包器支持对 Node.js 内置模块的同步 CommonJS require()。纯 ESM Worker 没有全局 require()。 Node.js 内置模块对象可写,因此 graceful-fs 之类的依赖可以在加载时打补丁。补丁仅留在其自己的 isolate 中。 导入其他 Node.js 模块会成功,但其首次调用会抛错。

Cache

celld 没有共享边缘缓存,因此提供的是永远 miss 的缓存。 put() 会验证并消费响应但不存储任何内容,match() 返回 undefined,delete() 返回 false。

TCP sockets

socket 的存活不能超过其事件。Durable Object 必须在下一次事件中重连。 celld 用内置的 Mozilla 根证书库验证 TLS 服务器。 celld 不封锁 Cloudflare 封锁的目标端口。出口策略由 fleet 网络控制。

BroadcastChannel

该类存在以便打包能加载,但其构造函数会抛出异常。

Compatibility flags

celld 支持以下兼容性标志:

delete_all_deletes_alarm js_rpc fetcher_no_get_put_delete sqlite_vec websocket_standard_binary_type static-assets 导航类标志

其他所有标志 celld 都接受但不生效。 Cloudflare.compatibilityFlags 只报告被支持的标志。

Wrangler configuration

celld deploy 接受 wrangler.jsonc 或 wrangler.json,不接受 wrangler.toml。 name 值须为 1 到 63 个小写 ASCII 字母、数字或内部连字符,不能以连字符开头或结尾。 接受的顶层键:

$schema、name、main 和 no_bundle compatibility_date 和 compatibility_flags durable_objects 和 migrations assets、services、triggers 和 vars d1_databases、kv_namespaces、queues、workflows 和 r2_buckets worker_loaders 和 containers define 和 rules

其他任何顶层键(包括 routes)都会导致部署终止。 define 和 rules 会传给 esbuild 运行。每个 define 值是一个 JavaScript 表达式,与 Wrangler 相同。rule 类型必须是 Text、Data 或 CompiledWasm,且每个 glob 必须形如 /*.ext 或 *.ext,因为 esbuild 按扩展名选择 loader。两条规则给同一扩展名指定不同类型会导致部署终止。celld 已对 /*.wasm 应用 CompiledWasm,因此 .wasm 只能使用该类型。 no_bundle 会跳过 esbuild,因此 no_bundle 与 define 或 rules 同时使用会导致部署终止。 纯静态资源项目可省略 main。celld deploy 会拒绝不安全的资源路径,且 .assetsignore 需要 Wrangler 支持。

运维限制参见 Limitations。

本篇用到的工具

评论 (0)