第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
#[event(fetch)]
async fn fetch(req: Request, env: Env, _ctx: Context) -> Result
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,其中包含该文件的名称。