第13章 Dynamic Workers:动态加载与运行时编译机制解析
文档:Dynamic Workers(动态 Worker)
Dynamic Worker 指由运行中的 Worker 在运行时提供、并通过 Worker Loader 绑定加载的 Worker 代码,比如用户上传的代码或模型生成的代码。celld 会把代码编译成加载器所在节点上的一个独立 V8 isolate。Cloudflare 目前以 open beta 形式提供该功能,API 可能会变化。标准 API 请参阅 Cloudflare Dynamic Workers 文档和 API reference。
示例
Dynamic Workers 示例会加载一个 Worker,并把它的调用记录发送给一个 Tail Worker。
index.js
```js import { WorkerEntrypoint } from "cloudflare:workers";
const WORKER_ID = "hello-v1"; const WORKER_MAIN = "worker.js"; const WORKER_SOURCE = ` export default { fetch() { console.log("hello from loaded code"); return new Response("Hello from a Dynamic Worker!\\n"); } }; `;
export class DynamicWorkerTail extends WorkerEntrypoint { tail(events) { for (const event of events) { for (const log of event.logs) { console.log(`dynamic-worker-tail: ${log.message.join(" ")}`, { workerId: this.ctx.props.workerId, level: log.level, }); } } } }
export default { fetch(request, env, ctx) { const worker = env.LOADER.get(WORKER_ID, () => ({ compatibilityDate: "2025-01-01", mainModule: WORKER_MAIN, modules: { [WORKER_MAIN]: WORKER_SOURCE }, tails: [ ctx.exports.DynamicWorkerTail({ props: { workerId: WORKER_ID }, }), ], })); return worker.getEntrypoint().fetch(request); }, }; ```
wrangler.jsonc
```jsonc { "name": "dynamic-worker-tails", "main": "index.js", "compatibility_date": "2026-01-01", "worker_loaders": [{ "binding": "LOADER" }] } ```
API
env.LOADER.get(id, getCode) 以字符串 id 加载一个 Worker;env.LOADER.load(code) 加载匿名 Worker。
getCode 返回一个 WorkerCode 对象,包含 mainModule、modules、compatibilityDate、compatibilityFlags、env、globalOutbound、limits 和 tails。
stub.getEntrypoint(name, options) 返回默认导出或具名 WorkerEntrypoint 的 Fetcher。
stub.getDurableObjectClass(name, options) 返回一个 Durable Object 类,例如用于某个 facet。
stub.dispose() 释放已加载的 Worker。
加载 Worker
worker_loaders 条目与 Wrangler 一样,只接受绑定名。如果该条目设置了 tails 或 limits,celld 会终止部署;请在 WorkerCode 对象中设置,或在 getEntrypoint() 调用中设置 limits。
celld 只在需要编译时才调用 env.LOADER.get(id, getCode) 的 getCode 回调,因此 getCode 中的异常会在首次使用该 Worker 时抛出,而不是在 get() 时。
modules 的值可以是模块对象,例如 { wasm: bytes },WebAssembly 页面演示了这种形式。与 workerd 一样,celld 不接受裸字节。
相对导入会相对于导入方模块的名称解析,因此只要映射中包含 dir/b.js,dir/a.js 就可以导入 ./b.js。
与 workerd 一样,compatibilityDate 是必填项。
模块源码默认总计不超过 64 MiB,与 workerd 相同。运维人员可以通过每个节点上的 CELLD_MAX_DYNAMIC_WORKER_CODE_BYTES 设置更大的字节数。已加载代码无法提高该上限,堆、执行时长和准入限制依然生效。
当 WorkerCode.limits 和 getEntrypoint() 同时设置了某个限制时,celld 取较小的值。
隔离边界
已加载的 isolate 拥有自己的上下文和堆,但运行在加载器的进程中。它不是第二个进程,也不是虚拟机,因此这个边界只限定代码的可寻址范围,不承诺 V8 逃逸安全性。如果需要内核级边界,请在命名运行时的容器中运行代码,详见 Containers 页面关于隔离边界的说明。
已加载的 Worker 拿不到部署的任何绑定和 vars 条目,也拿不到 Worker Loader 绑定,因此无法加载其他 Worker。它只能访问自己 WorkerCode 中的 env。能力调用就是一次进入加载器 isolate 的 RPC。celld 以函数参数而非全局变量的方式把宿主操作传给内部脚本,因此 globalThis 上不会暴露任何宿主操作。
当 WorkerCode 未指定 globalOutbound 时,已加载 Worker 继承加载器的出口策略。若值为 null,fetch() 和 connect() 会抛出异常。每次 fetch() 都经由加载器通过一个 Fetcher 中转。通过 Fetcher 调用 connect() 或建立 WebSocket 会抛出异常,因为 celld 的服务协议不支持双向隧道。
生命周期与缓存
get(id, getCode) 在同一宿主 isolate 的同一个 loader 绑定内按 id 记忆已编译的 Worker,因此模块级作用域在该范围内跨调用保留。每个 isolate、每个节点、每个 worker_loaders 条目都有独立的映射,各自需要重新编译。Cloudflare 将这种复用描述为"可能发生但不保证"。load(code) 每次调用都会重新编译。
只要 stub、entrypoint、Durable Object 类或运行中的 facet 还存在,其已加载的 Worker 就保持存活。id 映射持有弱引用,因此最后一个引用消失后,垃圾回收器可以在任意时间释放该 Worker,之后的 get() 会重新执行 getCode。
stub 的 dispose() 方法会释放其已加载的 Worker 并从映射中移除该 id。同一加载的其他 stub 无法发起新调用,进行中的调用会正常完成。
当宿主 isolate 退役时,celld 会在进行中的调用结束后丢弃所有已加载的 Worker。已加载 Worker 的存续期绝不会超过其加载器,重新部署也会重新编译代码。
与 Cloudflare 的差异
进程限制为 256 个存活的 Dynamic Worker,且每个脚本代最多占 255 个槽位,因此单个 loader 无法独占整个进程。所有 loader 和脚本共享进程限额,任一限额超限都会抛出异常。
进程会拒绝已移除的 CELLD_MAX_LOADED_WORKERS 环境变量。
getEntrypoint() 支持 props 和 limits 选项,而 getDurableObjectClass() 只支持 props。structured-clone 编码后的 props 值最大为 1 MiB。
globalOutbound 的 Fetcher 不能使用 connect() 或 WebSocket。
WorkerCode.tails 数组接受 Service Binding Fetcher。每次 Dynamic Worker fetch 调用结束后,每个 Fetcher 会收到一个事件,其中包含请求元数据、响应状态、console 日志、未捕获异常以及调用结果。
celld 对每次调用最多记录 256 KiB 的序列化 console 日志。当下一条完整记录超过该上限时,就停止记录。
Tail 投递在响应可用之后才开始。Tail Worker 的失败不影响响应,celld 会把失败信息写入控制台。
celld 会在 WorkerCode.limits 和 getEntrypoint() 调用中强制执行 cpuMs 和 subRequests,并拒绝 allowExperimental。
WorkerCode.env 接受 structured-clone 值和 Service Binding 能力,编码后的值与能力 props 总计不超过 1 MiB。
已加载 Worker 的 entrypoint 不能迁移到其他 Worker,Awaitable 和 pipelined 属性也不可用。
Cloudflare 兼容性页面列出了可用的运行时 API 以及不支持的服务。