企业官网建设流程全解析

workerd 的 JSG（JavaScript Glue）绑定层完全指南：架构、宏绑定模式、GC 不变量与审查规范

【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd

导读

JSG（JavaScript Glue）是 workerd（Cloudflare Workers 的开源运行时）中连接 KJ 风格的 C++ 运行时内核与 V8 JavaScript 引擎的宏驱动绑定层。本文以src/workerd/jsg/AGENTS.md为骨架，系统讲解 JSG 的核心架构、关键源码文件职责、资源类型（Resource Type）的标准绑定写法、C++ 侧捕获 JS 异常的推荐方式、必须规避的反模式，以及十二条必须在编写/修改 JSG 代码时遵守的 GC 与模块评估不变量。读完本文，你将能够在 workerd 中正确编写、审查并维护 JSG 绑定代码，理解visitForGc()与 V8 垃圾回收的关系，并掌握模块评估嵌套时的防护机制。

一、JSG 是什么：宏驱动的 C++/V8 绑定层

JSG 的本质是一条"宏驱动的绑定层"：通过一组 C++ 宏，把 C++ 类型声明为 JavaScript 可见的资源（Resource）或结构体（Struct），并自动完成两者之间的类型转换。

• 对资源类型而言，JSG 把 C++ 对象映射为带有原型与方法的 JavaScript 对象，JS 访问成员时会回调 C++；
• 对值类型/结构体而言，JSG 把 C++ 结构体深拷贝为普通 JS 对象，转换后 C++ 不再参与。

这一分层理念源自 KJ 风格指南中对 "Value Types" 与 "Resource Types" 的区分（叙述性教程见 docs/jsg.md，速查参考手册见 src/workerd/jsg/README.md）。从源码结构看，src/workerd/jsg/目录下全部绑定逻辑均围绕v8::Isolate、v8::Context与模板元编程展开，是 workerd 所有 Worker API（如cloudflare:*、node:*内置模块）得以暴露给 JS 的基础设施。

二、关键文件地图：JSG 源码布局

AGENTS.md 给出了完整的文件职责表，逐一对应src/workerd/jsg/下的真实文件：

目录中还配套了大量针对性测试文件（如 jsg-test.c++、struct-test.c++、weakref-test.c++、modules-new-test.c++、fast-api-test.c++），是理解各组件行为的活文档。

三、标准绑定模式（BINDING PATTERN）

AGENTS.md 给出了资源类型的标准写法，这是所有 Worker API 绑定的模板：

class MyType: public jsg::Object { static jsg::Ref<MyType> constructor(kj::String s); int getValue(); void doThing(jsg::Lock& js, int n); JSG_RESOURCE_TYPE(MyType) { // or (MyType, CompatibilityFlags::Reader flags) JSG_METHOD(doThing); JSG_PROTOTYPE_PROPERTY(value, getValue, setvalue); JSG_NESTED_TYPE(SubType); JSG_STATIC_METHOD(create); } void visitForGc(jsg::GcVisitor& visitor) { visitor.visit(ref, v8ref); // MUST trace all Ref<T>/V8Ref<T>/JsRef<T> } jsg::Ref<Other> ref; jsg::V8Ref<v8::Object> v8ref; };

3.1JSG_RESOURCE_TYPE宏背后发生了什么

JSG_RESOURCE_TYPE(Type, ...)在 jsg.h 中展开为一段嵌入类内部的静态成员与友元声明，核心动作包括：

• 记录JsgKind::RESOURCE类型标记，建立jsgThis/jsgSuper的继承链上下文；
• 生成jsgGetMemoryName()、jsgGetMemorySelfSize()、jsgGetMemoryInfo()等内存追踪方法（供MemoryTracker使用）；
• 生成jsgVisitForGc()虚函数覆写，并委托给visitSubclassForGc<Type>(this, visitor)—— 这正是visitForGc()不变量被自动接线的底层机制；
• 声明static void jsgConfiguration(__VA_ARGS__)与registerMembers(Registry&, ...)，将宏块内的JSG_METHOD/JSG_PROTOTYPE_PROPERTY等成员注册逻辑挂接到模板注册体系。

也就是说，"绑定块"里的每一行宏，最终都会由resource.h的模板元编程翻译成v8::FunctionTemplate/v8::ObjectTemplate上的回调。该宏可选第二个参数CompatibilityFlags::Reader flags，用于按兼容性标志条件性地暴露成员（见下）。

3.2 关键约定

• 分配资源对象：js.alloc<MyType>(args...)—— 返回jsg::Ref<MyType>；
• 值类型：JSG_STRUCT(field1, field2)—— 按值自动转换，只映射列出的字段；
• jsg::Lock&：JS 执行上下文句柄，通过方法参数按线程传递，是访问 isolate 与 context 的统一入口；
• TypeHandler<T>&尾参：作为最后一个参数提供手动类型转换能力；
• 兼容性标志参数：在JSG_RESOURCE_TYPE上携带CompatibilityFlags::Reader可以按标志门控成员，例如：

JSG_RESOURCE_TYPE(MyApi, workerd::CompatibilityFlags::Reader flags) { JSG_METHOD(oldMethod); // 始终暴露 if (flags.getMyNewFeature()) { JSG_METHOD(newMethod); // 仅当标志开启时暴露 } }

标志定义位于src/workerd/io/compatibility-date.capnp。

3.3 类型映射速览（编写绑定的基础）

绑定模式依赖自动类型转换。完整的原始映射表见 src/workerd/jsg/README.md，这里给出最常用的几组：

• 标量：bool→v8::Boolean；double/int/int32_t→number；int64_t/uint64_t→v8::BigInt（bigint）；
• 字符串：kj::String（拥有）→string；kj::StringPtr（视图，仅 C++→JS）；jsg::USVString为 USV 编码变体；注意JSstring永远不会转换成kj::StringPtr；
• 空值语义：kj::Maybe<T>空值 →null，jsg::Optional<T>空值 →undefined，且jsg::Optional<T>遇到 JSnull会抛错（除非用jsg::LenientOptional<T>静默忽略）；
• 容器：kj::Array<T>↔ JSArray（输入必须是数组）；jsg::Sequence<T>接受任意Symbol.iterator对象，输出恒为数组；jsg::Dict<T>↔ 键为字符串、值类型统一的普通对象；kj::OneOf<T...>为 Web IDL 联合类型（编译期校验）；
• 引用：jsg::Ref<T>（资源强引用）、jsg::V8Ref<T>（V8 值持久强引用）、jsg::Value（V8Ref<v8::Value>别名）、jsg::WeakRef<T>等弱引用家族。

四、错误处理：用JSG_TRY/JSG_CATCH替代裸try/catch

AGENTS.md 明确指出：在 C++ 中捕获 JS 异常请使用JSG_TRY(js) { ... } JSG_CATCH(exception) { ... }，其中js是jsg::Lock&参数，exception是包含被抛出 JS 异常的jsg::Value。旧的js.tryCatch(fn)已废弃，将逐步移除。

其实现位于 jsg.h：JSG_TRY(js)构造一个JsgCatchScope _jsgTryCatch(js)并进入try；JSG_CATCH展开为catch (...)，调用_jsgTryCatch.catchException(...)把任意 C++ 异常（包括JsExceptionThrown与kj::Exception）统一转换为jsg::Value，随后通过goto跳到处理块。因此：

• JSG_CATCH不是真正的 catch—— 块内没有"当前异常"可供throw重抛；想重抛必须显式调用js.throwException(kj::mv(exception))；
• 可通过第二参数传入ExceptionToJsOptions（如{.ignoreDetail = true}）自定义转换行为；
• JSG_TRY/JSG_CATCH使用硬编码的内部变量名_jsgTryCatch（已用KJ_SILENCE_SHADOWING屏蔽嵌套阴影告警）。

配套的错误宏定义于 exception.h：

JSG_REQUIRE(cond, TypeError, "Expected a valid value, got ", value); auto& val = JSG_REQUIRE_NONNULL(maybeValue, TypeError, "Value must not be null"); JSG_FAIL_REQUIRE(RangeError, "Index ", index, " is out of bounds"); JSG_ASSERT(cond, Error, "Internal assertion failed");

错误类型可选TypeError、Error、RangeError或DOMException系列（DOMOperationError、DOMInvalidStateError、DOMNotFoundError、DOMAbortError等），完整目录见 README 错误类型目录。注意JSG_REQUIRE的消息参数会经kj::str()拼装，与KJ_REQUIRE的拼接语义不同。

五、反模式清单（ANTI-PATTERNS）：必须规避的坑

AGENTS.md 总结了如下红线，任何一条都可能引发 GC 损坏或语义错误：

• 绝不要对V8Ref<T>做不透明包装（opaque-wrap）—— 直接使用 handle；
• 绝不要使用v8::Context的 embedder data 槽位 0（ContextPointerSlot::RESERVED，V8 保留）；
• 绝不要持有可追踪句柄（Ref<T>/V8Ref<T>）却不写入visitForGc—— 会造成 GC 损坏；
• 绝不要在 Fast API 调用中使用FastOneByteString（GC 损坏风险）；
• 绝不要对Ref<Object>解包 —— 改用V8Ref<v8::Object>；
• JSG_CATCH不是真正的 catch —— 无法用throw重抛；
• NonCoercible<T>与 Web IDL 最佳实践相悖，新 API 中应避免；
• Rust 侧 JSG 绑定参见 src/rust/jsg/ 与 src/rust/jsg-macros/，GC 追踪（Traced+GarbageCollected）见 src/rust/jsg-macros/README.md。

反模式对应的正面替代：属性默认用原型属性；持久化 V8 值用V8Ref<T>/JsRef<T>；对象标识保持用MemoizedIdentity<T>；弱引用用WeakRef<T>/WeakV8Ref<T>/WeakJsRef<T>（它们不可被visitForGc访问，强行访问是编译错误）。

六、不变量规则（INVARIANTS）：编写/修改 JSG 代码的十二条铁律

AGENTS.md 强调，以下规则在编写或修改任何 JSG 代码时必须遵守。逐条展开如下：

6.1 必须实现visitForGc()

任何持有Ref<T>、V8Ref<T>、JsRef<T>、Function<T>、Promise<T>或Promise<T>::Resolver的资源类型，必须实现visitForGc()。完整 GC 可访问类型清单见 README §GC-Visitable Types，除上述外还包括Value、HashableV8Ref<T>、Optional<T>/LenientOptional<T>（当T可访问）、Sequence<T>（用visitor.visitAll）、Generator<T>/AsyncGenerator<T>、kj::Maybe<T>（当T可访问）。

void visitForGc(jsg::GcVisitor& visitor) { visitor.visit(ref, v8ref); // 一次调用可访问多个字段 }

6.2 必须访问全部 GC 可访问字段

遗漏任何一个可访问字段都会导致 GC 损坏 —— 因为 V8 的标记-清除回收器无法看到被 C++ 持有、但未在嵌入器图中标记的对象。

6.3 不得把v8::Local<T>/JsValue存为类成员

这类句柄只在当前作用域内有效（调试构建会强制栈上分配）。需要持久化时使用V8Ref<T>或JsRef<T>。

6.4 不得在JSG_STRUCT字段中放v8::Global<T>/v8::Local<T>

结构体字段应使用jsg::V8Ref<T>或jsg::JsRef<T>。

6.5 不得把v8::Global<T>/v8::Local<T>放入kj::Promise

这一点在编译期被删除（deleted），从类型系统层面杜绝悬挂句柄随异步任务逃逸。

6.6 不得把jsg::Lock传入 KJ promise 协程

Lock与线程/isolate 强绑定，跨越协程边界会导致未定义行为；需要异步延续时捕获所需值而非锁本身。

6.7JSG_SERIALIZABLE必须出现在JSG_RESOURCE_TYPE块之后，而非块内

序列化声明是独立于成员注册的另一个机制（见 README 序列化模式）：

JSG_RESOURCE_TYPE(MyType) { // ...成员... } JSG_SERIALIZABLE(SerializationTag::MY_TYPE_V1); // 必须在块外

serialize()/deserialize()的签名约定为：

void serialize(jsg::Lock& js, jsg::Serializer& serializer); static jsg::Ref<T> deserialize(jsg::Lock& js, TagEnum tag, jsg::Deserializer& deser);

6.8 序列化标签枚举值一旦产生过数据就不得更改

首个标签代表当前版本，后续标签为可接受的旧版本；deserialize()收到标签后据此做版本分发。改动标签会破坏历史数据的反序列化兼容性。

6.9Ref<T>所有权必须沿 owner → owned 单向流动

反向引用（owned → owner）用裸T&或kj::Maybe<T&>。这防止jsg::Ref<T>形成无法打破的引用环——C++ 对象是引用计数的，GC 只能回收 JS 包装对象，环中的 C++ 对象会一直存活。

6.10 默认优先JSG_PROTOTYPE_PROPERTY，除非有明确理由用实例属性

实例属性（JSG_INSTANCE_PROPERTY）是每个实例的自有属性，会破坏 GC 优化（阻止包装对象的快速收集路径）。属性选择矩阵见 README 属性决策矩阵。

6.11 用// NOLINT(jsg-visit-for-gc)记录有意的"不访问"

当某 GC 可访问字段有意不被访问（例如由kj::Rc拥有、JS 不可达的对象，或已通过其他机制访问的类型），用该注释抑制jsg-visit-for-gcclang-tidy 诊断，并简要说明为何跳过是安全的。

6.12 模块求值不得在嵌套状态下排空微任务队列

这是最微妙的一条。在祖先模块仍处于kEvaluating状态时排空微任务队列，可能提前运行异步模块的 fulfillment 回调，触发 V8 致命 CHECK（status() >= kEvaluatingAsync）。防护机制包括：

• 求值深度由 RAII 类型Lock::ModuleEvaluationScope跟踪，可通过js.isEvaluatingModule()查询；
• 新旧两个模块注册表在完成挂起的顶层 await（top-level await）前都会检查该状态；
• 任何调用v8::Module::Evaluate()的代码路径都必须持有ModuleEvaluationScope，包括嵌入方提供的求值回调（ModuleRegistry::Builder::setEvalCallback），否则防护会被静默绕过；
• 能向自身调用方返回 promise 的调用者，可传InstantiateModuleOptions::ALLOW_PENDING_EVALUATION接收挂起求值 promise 而不是报错。

源码佐证：Lock::ModuleEvaluationScope与Lock::isEvaluatingModule()实现在 jsg.c++，旧注册表在 modules.c++ 中于module->Evaluate()前后持有该作用域并据此校验选项，新注册表在 modules-new.c++ 同样如此；行为测试与注释见 modules-new-test.c++。

6.13 构建期强制：jsg-visit-for-gcclang-tidy 检查

不变量 1 与 2 并非仅靠自觉：jsg-visit-for-gcclang-tidy 检查（目标//tools/clang-tidy:workerd-lint，源码见 tools/clang-tidy/visit-for-gc.c++ 与 tools/clang-tidy/visit-for-gc.h）会在构建期自动检测缺失的visitForGc实现与未访问字段，仓库内配套正反例测试（visit-for-gc-positive-test.c++、visit-for-gc-negative-test.c++及visit-for-gc-test.sh）可验证其判定逻辑。

七、代码审查规则（CODE REVIEW RULE）

AGENTS.md 明确要求：审查 JSG 相关改动时，必须检查改动是否需要同步更新以下文档：

• src/workerd/jsg/README.md—— 若改动新增/修改类型映射、宏、错误类型、序列化模式或速查表；
• docs/jsg.md—— 若改动影响教程内容、新增模式或改变 API 使用示例；
• 本文档（src/workerd/jsg/AGENTS.md）—— 若改动增删文件、改变架构概述或引入新的不变量。

行为或架构层面的改动不应在缺少对应文档更新的情况下合入。这一规则把"文档即规范"固化进了变更流程，确保 JSG 的宏目录、错误目录与不变量清单始终与代码同步演进。

结语

JSG 是 workerd 得以把数千行 C++ API 优雅暴露给 JavaScript 的核心黏合层：宏驱动的声明式绑定降低了样板代码量，visitForGc()与ModuleEvaluationScope则从机制上保证了嵌入器对象图与 V8 GC、模块求值深度的正确协作。无论是为 workerd 新增一个cloudflare:*内置模块，还是审查既有绑定改动，本文梳理的绑定模式、反模式清单、十二条不变量与文档同步规则都值得作为第一手参考；更细的类型映射表、宏目录与错误目录可直接查阅 src/workerd/jsg/README.md，而逐步上手示例见 docs/jsg.md。

【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd