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

第6章 WebAssembly

文档 WebAssembly Worker 打包文件可以导入 .wasm 文件。与 Wrangler 类似,导入的是编译后的模块,而非原始字节。

import addModule from "./add.wasm";

const { exports } = new WebAssembly.Instance(addModule);

export default { fetch() { return new Response(String(exports.add(2, 3))); }, };

celld deploy 会将每个导入的 wasm 文件随打包文件一起上传,并在部署中标记 wasm-v1 特性。早于该特性的节点会拒绝部署,因此混合集群会在部署阶段而非请求阶段失败。

celld 每个进程只编译一次每个 wasm 模块,后续的隔离区和单元激活均可复用该模块。

示例

WebAssembly 示例编译了一个 Rust Durable Object,并导入了它的 WebAssembly 模块。

Cargo.toml [package] name = "counter-demo-rs" version = "0.1.0" edition = "2021"

# 此配置将示例排除在引擎工作区之外。 [workspace]

[lib] crate-type = ["cdylib"]

[dependencies] worker = "0.8.5" serde_json = "1"

src/lib.rs use worker::*;

#[durable_object(fetch)] pub struct Counter { state: State, }

impl DurableObject for Counter { fn new(state: State, _env: Env) -> Self { Self { state } }

async fn fetch(&self, req: Request) -> Result { let n: u64 = self.state.storage().get("n").await.ok().flatten().unwrap_or(0); let n = n + 1; self.state.storage().put("n", &n).await?; let path = req.path(); let name = path.strip_prefix("/c/").unwrap_or(""); Response::from_json(&serde_json::json!({ "name": name, "n": n, "lang": "rust" })) } }

#[event(fetch)] async fn fetch(req: Request, env: Env, _ctx: Context) -> Result { let path = req.path(); if let Some(name) = path.strip_prefix("/c/").filter(|name| !name.is_empty()) { let namespace = env.durable_object("COUNTER")?; let stub = namespace.id_from_name(name)?.get_stub()?; return stub.fetch_with_request(req).await; } let status = if path == "/" { 200 } else { 404 }; Ok( Response::ok("celld rust demo. Try: curl http://localhost:8080/c/hello\n")? .with_status(status), ) }

wrangler.jsonc { "name": "counter-demo-rs", "main": "build/worker/shim.mjs", "compatibility_date": "2026-01-01", "durable_objects": { "bindings": [{ "name": "COUNTER", "class_name": "Counter" }] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }] }

预构建 Worker 设置 no_bundle: true 后,celld 会逐字节保留入口 JavaScript 文件。它会在包含 main 的目录下应用 Wrangler 默认的 /*.wasm 和 /*.wasm?module 模式。例如,main: "./dist/shim.mjs" 可以从 dist 导入 "./add.wasm" 或 "./lib/add.wasm"。模块名称保留这些相对路径。此模式不需要 esbuild。

扫描会上传 JavaScript 未导入的 WASM 文件,因此请专用构建输出目录。它跳过 .git、.celld、.wrangler 以及指向目录的符号链接。如果符号链接的名称匹配 WASM 模式,它会拒绝该链接,请改为将文件复制到构建输出目录中。

celld 不实现 Wrangler 的其他模块发现设置。

它不会发现额外的 JavaScript 模块,也不接受 rules、base_dir 或 find_additional_modules 配置。JavaScript 必须已经打包完成,其 WASM 导入必须相对于入口目录。

使用 workers-rs 的 Rust workers-rs 会构建一个 JavaScript 垫片和一个 wasm 文件,垫片是 celld deploy 的普通入口点。

安装构建工具:cargo install worker-build。 构建 crate:worker-build --release。 将配置指向垫片:

{ "name": "my-app", "main": "./build/worker/shim.mjs", "compatibility_date": "2026-01-01", }

部署:celld deploy。

celld 通过垫片的 Proxy 封装解析入口点和 Durable Object 类。如果 workers-rs API 需要 Cloudflare 兼容性中缺失的运行时特性,则无法正常工作。

动态 Worker 将 wasm 作为 { wasm: bytes } 传递给动态加载的 worker 模块映射,worker 导入的是编译后的模块。celld 会拒绝裸字节,与 workerd 的行为一致。

const worker = env.loader.load({ compatibilityDate: "2025-01-01", mainModule: "main.js", modules: { "main.js": `import m from "./add.wasm"; ...`, "add.wasm": { wasm: wasmBytes }, }, });

限制

Wasm 字节数与 JavaScript 模块一样计入部署大小限制。无法编译的模块会导致导入模块抛出 WebAssembly.CompileError,其中包含该文件的名称。

本篇用到的工具

评论 (0)