Lynx 共享 NAPI 环境与多引擎 Runtime-Proxy 胶水层深度解析【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx本篇技术指南围绕core/runtime/common/napi目录展开它是 Lynx 运行时中面向V8、QuickJS、JavaScriptCoreJSC、JSVM 等多套 JS 引擎提供统一 NAPI 环境的共享胶水层。通过阅读本文你将理解NapiEnvironment与NapiRuntimeProxy的职责划分、Attach/Detach 生命周期契约、多后端工厂机制以及为保证「后端无关」需要遵守的编辑规则与回归验证方法runtime_tests_exec。一、目录定位共享 NAPI 环境与 runtime-proxy 胶水层根据 AGENTS.md 的 Scope 定义该目录不隶属于任何单一 JS 引擎而是承载两类核心职责的共享代码共享 NAPI 环境NAPI Environment提供一套与具体引擎解耦的NapiEnvironment上下文负责模块注册、加载与销毁通知让上层业务无需关心底层是 V8 还是 QuickJS。Runtime-Proxy 胶水层通过NapiRuntimeProxyInterface抽象把 NAPI 的napi_env与具体引擎运行时Runtime绑定起来包括 Loader 的装载/卸载、未捕获异常处理等。从构建系统看目录同时产出多个 source set见 BUILD.gnnapi_binding_core共享核心、napi_binding_jsc、napi_binding_quickjs、napi_binding_v8、napi_binding_jsvm、napi_binding_oliver各引擎的专属实现被隔离在各自的 source set 中这正是「后端无关」设计在构建层面的落地。二、NapiEnvironment统一环境上下文NapiEnvironment 是目录对外暴露的核心门面其设计要点如下。2.1 Module可插拔的业务模块class Module { public: virtual ~Module() default; virtual void OnLoad(Napi::Object app) 0; virtual bool IsLazy() { return false; } // NapiEnvironment provides detach event for registered modules to do // finalization. Compared with RefTracker::FinalizeAll(), it is safer to // interop with JS engine in this callback because it happens before // runtime proxy is detached. It is not required that a module be loaded // to receive this callback. virtual void OnEnvDetach(Napi::Env env) {} };关键点OnLoad是模块注入入口可把构造器、全局对象挂到 JS 侧测试中正是通过TestModule::OnLoad(global)注入TestElement、TestContext构造器见 napi_environment_unittest.ccOnEnvDetach是环境分离时的终结回调注释中特别强调它发生在 runtime proxy 解绑之前比RefTracker::FinalizeAll()更安全可以在回调中安全地与 JS 引擎交互模块无需被加载也会收到OnEnvDetach回调It is not required that a module be loaded to receive this callback。2.2 DelegateUI 线程与 JS 线程差异的收纳器class Delegate { public: virtual void OnAttach(Napi::Env env) {} // 注入全局对象/构造器 virtual void OnDetach(Napi::Env env) {} // 清理 virtual void RegisterModule(const std::string name, std::unique_ptrModule module) {} virtual Module* GetModule(const std::string name) { return nullptr; } virtual void LoadInstantModules(Napi::Object lynx) {} virtual void NotifyRuntimeReady(Napi::Env env, Napi::Object lynx) {} };NapiEnvironment注释明确说明「NapiEnvironment contains common logic shared between UI and JS threads. When there are differences, we put them into the Delegate (NapiLoader).」即 UI 线程与 JS 线程的差异全部下沉到Delegate具体实现是 NapiLoader核心环境逻辑保持单一实现。2.3 Attach/Detach 生命周期Attach/Detach 实现揭示了严格的有序调用链void NapiEnvironment::Attach() { if (attached_) return; attached_ true; proxy_-Attach(); proxy_-SetupLoader(); proxy_-SetUncaughtExceptionHandler(); Napi::Env env proxy_-Env(); env.SetInstanceData(kEnvClassID, this, nullptr, nullptr); delegate_-OnAttach(env); } void NapiEnvironment::Detach() { if (!attached_) return; attached_ false; Napi::Env env proxy_-Env(); delegate_-OnDetach(env); proxy_-RemoveLoader(); proxy_-Detach(); }Attach顺序proxy_-Attach()→SetupLoader()→SetUncaughtExceptionHandler()→ 通过SetInstanceData把自身与napi_env绑定 →delegate_-OnAttach(env)Detach顺序与 Attach 镜像先delegate_-OnDetach(env)再RemoveLoader()最后proxy_-Detach()NapiEnvironment::From(Napi::Env env)通过env.GetInstanceDataNapiEnvironment(kEnvClassID)反查环境实例kEnvClassID使用reinterpret_castuint64_t(kEnvClassID)的地址作为唯一 ID避免魔法数字冲突。三、NapiRuntimeProxy跨引擎的运行时胶水3.1 接口抽象NapiRuntimeProxyInterface 定义了引擎无关的最小契约class NapiRuntimeProxyInterface { public: virtual void Attach() 0; virtual void Detach() 0; virtual Napi::Env Env() 0; virtual void SetJSRuntime(base::UnsafeWeakPtrRuntime runtime) 0; virtual base::UnsafeWeakPtrRuntime GetJSRuntime() 0; virtual void SetupLoader() 0; virtual void RemoveLoader() 0; virtual void SetUncaughtExceptionHandler() 0; };注意js_runtime_使用UnsafeWeakPtrRuntime持有 JS 运行时而非强引用——这是避免 runtime 生命周期循环依赖的关键设计。3.2 多后端工厂与运行时创建NapiRuntimeProxy::Create 依据runtime.type()分发到不同后端JSRuntimeType::v8通过NapiRuntimeProxyV8Factory工厂创建。工厂接口注释napi_runtime_proxy_v8_factory.h说明它「Used by DevTool and dynamic v8 to set a factory from another shared library (so as to avoid bloating liblynx.so)」——即由 DevTool 或动态 V8 从另一个共享库注入工厂避免膨胀 liblynx.soJSRuntimeType::jsc仅OS_IOS || OS_OSX平台可用直接构造NapiRuntimeProxyJSCJSRuntimeType::quickjs从QuickjsRuntime取出共享上下文构造NapiRuntimeProxyQuickjsJSRuntimeType::jsvm通过NapiRuntimeProxyJSVMFactory工厂创建。对应的导出注册接口供外部注入LYNX_EXPORT void RegisterV8RuntimeProxyFactory(NapiRuntimeProxyV8Factory* factory); LYNX_EXPORT void RegisterJSVMRuntimeProxyFactory(NapiRuntimeProxyJSVMFactory* factory);引擎专属实现文件按命名清晰分离napi_runtime_proxy_v8.cc、napi_runtime_proxy_quickjs.cc、napi_runtime_proxy_jsc.cc、napi_runtime_proxy_jsvm.cc与 AGENTS.md 中「backend-specific proxy specializations should stay in their dedicated files」的编辑规则一一对应。3.3 Loader 机制与共享上下文兼容SetupLoader实现见揭示了几条关键细节默认 Loader 名称为napiLoaderOnRT runtimeIdis_safe_napi_时使用固定名__lynxNapiLoader通过napi_setup_loader(env_, loader_.c_str())注册并在全局对象上挂载对单上下文runtime-getGroupId() -1做兼容额外把__lynxNapiLoader指向同一 Loader通过napiSharedMarker标记检测是否处于共享上下文shared context这是多 App/多实例场景下的防冲突手段RemoveLoader在销毁时删除对应全局键防止内存泄漏。3.4 未捕获异常处理SetUncaughtExceptionHandler通过binding::CallbackHelper::SetUncaughtExceptionHandler(env_, ReportError)注册。ReportErrornapi_runtime_proxy.cc#L152-L182会读取global.currentAppId与global.multiApps定位当前 App 代理再调用lynx.reportError上报USER_RUNTIME_ERROR若 App 已销毁app_proxy为 null/undefined则静默返回。四、安全沙箱RestrictedNapiRuntimeProxyDecoratorRestrictedNapiRuntimeProxyDecorator 是NapiRuntimeProxyInterface的装饰器为外部用户提供受限的napi_env——禁用napi_run_script与napi_get_global防止用户注入的模块破坏 Lynx 脚本运行时稳定性。实现要点napi_runtime_proxy.cc#L284-L337SetupLoader先保存原始napi_get_global函数指针然后把raw_env-napi_run_script与raw_env-napi_get_global替换为LynxHookedNapiRunScript/LynxHookedNapiGetGlobal这两个钩子函数直接抛错napi_run_script is not allowed in lynx module. napi_get_global is not allowed in lynx module.受限 Loader 名为napiRestrictedLoader runtimeId挂载一个含load方法的 exports 对象LoadRestrictedModule通过napi_find_module查找注册模块并用RestrictedModuleRegistry存于napi_env的 InstanceData做已加载模块缓存避免重复初始化。五、编辑规则与常见回归症状AGENTS.md 核心约束根据 AGENTS.md 的 Edit Rules维护该目录时必须遵守保持后端无关环境与 runtime-proxy 逻辑应尽可能与具体引擎解耦引擎专属的 proxy 特化必须放在各自专用文件napi_runtime_proxy_{v8,quickjs,jsc,jsvm}.cc谨慎处理生命周期特别小心 lifetime、runtime ownership如UnsafeWeakPtrRuntime的持有方式与跨引擎能力差异不同引擎对 NAPI 支持度不同。文档列出的两类常见回归症状正是评审和自测时的重点观察项NAPI 模块在一个引擎中正常、换引擎后失败通常是 proxy 改动破坏了后端无关性或依赖了某个引擎特有的 NAPI 行为环境创建/销毁仅在集成流程中回归孤立调用点无异常说明问题出在 Attach/Detach 的生命周期顺序如 Loader 未清理、InstanceData 残留或线程切换路径上需要结合集成测试排查。六、验证方式runtime_tests_exec 与单元测试AGENTS.md 声明该目录没有独立声明的可执行目标验证统一通过runtime_tests_exec完成。该目标定义在 core/runtime/BUILD.gn聚合:runtime_testset下全部 runtime 相关测试集。针对 NAPI 环境本身目录内置了专用单测 napi_environment_unittest.cc通过 QuickJS 上下文构造NapiRuntimeProxyQuickjs并驱动真实NapiEnvironment覆盖三类典型场景BasicScriptingTestAttach 后验证脚本执行env_.RunScript(321)返回 321、全局变量读写x 42、函数调用链路LoadModuleTest自定义TestDelegate在OnAttach中调用TestModule::OnLoad注入构造器验证new TestElement(test)、getContext缓存复用ctx ctx1、testPlusOne(41) 42等模块逻辑。若 NAPI 环境契约发生变更AGENTS.md 还建议同时检查附近 runtime common 与 value-wrapper 的测试覆盖——这提示 NAPI 环境与 value_wrapper 之间存在联动依赖。七、shim 层跨平台 NAPI 头文件统一shim/README.md 解释了目录内 shim 子目录的由来Android 上直接依赖 NAPI 源码而 iOS 上依赖发布的 NAPI Pod这一差异导致两边无法包含同一份头文件。shim 层shim_napi_env_jsc.h、shim_napi_env_quickjs.h、shim_napi_env_v8.h正是为了在 Lynx 代码中统一包含同一头文件而引入的适配层。该 README 同时注明「This should be fixed soon as Android is adopting libc_shared.so」说明这是一个临时的兼容性方案。八、小结core/runtime/common/napi是 Lynx 多引擎 NAPI 架构的枢纽NapiEnvironment提供统一的环境门面与模块生命周期NapiRuntimeProxy抽象出跨 V8/QuickJS/JSC/JSVM 的运行时胶水RestrictedNapiRuntimeProxyDecorator通过 hooknapi_run_script/napi_get_global构建安全沙箱。在修改该目录时请始终牢记 AGENTS.md 的三条铁律——后端无关、生命周期谨慎、跨引擎差异警觉——并通过runtime_tests_exec与目录内 QuickJS 单测验证改动。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Lynx 共享 NAPI 环境与多引擎 Runtime-Proxy 胶水层深度解析
Lynx 共享 NAPI 环境与多引擎 Runtime-Proxy 胶水层深度解析【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx本篇技术指南围绕core/runtime/common/napi目录展开它是 Lynx 运行时中面向V8、QuickJS、JavaScriptCoreJSC、JSVM 等多套 JS 引擎提供统一 NAPI 环境的共享胶水层。通过阅读本文你将理解NapiEnvironment与NapiRuntimeProxy的职责划分、Attach/Detach 生命周期契约、多后端工厂机制以及为保证「后端无关」需要遵守的编辑规则与回归验证方法runtime_tests_exec。一、目录定位共享 NAPI 环境与 runtime-proxy 胶水层根据 AGENTS.md 的 Scope 定义该目录不隶属于任何单一 JS 引擎而是承载两类核心职责的共享代码共享 NAPI 环境NAPI Environment提供一套与具体引擎解耦的NapiEnvironment上下文负责模块注册、加载与销毁通知让上层业务无需关心底层是 V8 还是 QuickJS。Runtime-Proxy 胶水层通过NapiRuntimeProxyInterface抽象把 NAPI 的napi_env与具体引擎运行时Runtime绑定起来包括 Loader 的装载/卸载、未捕获异常处理等。从构建系统看目录同时产出多个 source set见 BUILD.gnnapi_binding_core共享核心、napi_binding_jsc、napi_binding_quickjs、napi_binding_v8、napi_binding_jsvm、napi_binding_oliver各引擎的专属实现被隔离在各自的 source set 中这正是「后端无关」设计在构建层面的落地。二、NapiEnvironment统一环境上下文NapiEnvironment 是目录对外暴露的核心门面其设计要点如下。2.1 Module可插拔的业务模块class Module { public: virtual ~Module() default; virtual void OnLoad(Napi::Object app) 0; virtual bool IsLazy() { return false; } // NapiEnvironment provides detach event for registered modules to do // finalization. Compared with RefTracker::FinalizeAll(), it is safer to // interop with JS engine in this callback because it happens before // runtime proxy is detached. It is not required that a module be loaded // to receive this callback. virtual void OnEnvDetach(Napi::Env env) {} };关键点OnLoad是模块注入入口可把构造器、全局对象挂到 JS 侧测试中正是通过TestModule::OnLoad(global)注入TestElement、TestContext构造器见 napi_environment_unittest.ccOnEnvDetach是环境分离时的终结回调注释中特别强调它发生在 runtime proxy 解绑之前比RefTracker::FinalizeAll()更安全可以在回调中安全地与 JS 引擎交互模块无需被加载也会收到OnEnvDetach回调It is not required that a module be loaded to receive this callback。2.2 DelegateUI 线程与 JS 线程差异的收纳器class Delegate { public: virtual void OnAttach(Napi::Env env) {} // 注入全局对象/构造器 virtual void OnDetach(Napi::Env env) {} // 清理 virtual void RegisterModule(const std::string name, std::unique_ptrModule module) {} virtual Module* GetModule(const std::string name) { return nullptr; } virtual void LoadInstantModules(Napi::Object lynx) {} virtual void NotifyRuntimeReady(Napi::Env env, Napi::Object lynx) {} };NapiEnvironment注释明确说明「NapiEnvironment contains common logic shared between UI and JS threads. When there are differences, we put them into the Delegate (NapiLoader).」即 UI 线程与 JS 线程的差异全部下沉到Delegate具体实现是 NapiLoader核心环境逻辑保持单一实现。2.3 Attach/Detach 生命周期Attach/Detach 实现揭示了严格的有序调用链void NapiEnvironment::Attach() { if (attached_) return; attached_ true; proxy_-Attach(); proxy_-SetupLoader(); proxy_-SetUncaughtExceptionHandler(); Napi::Env env proxy_-Env(); env.SetInstanceData(kEnvClassID, this, nullptr, nullptr); delegate_-OnAttach(env); } void NapiEnvironment::Detach() { if (!attached_) return; attached_ false; Napi::Env env proxy_-Env(); delegate_-OnDetach(env); proxy_-RemoveLoader(); proxy_-Detach(); }Attach顺序proxy_-Attach()→SetupLoader()→SetUncaughtExceptionHandler()→ 通过SetInstanceData把自身与napi_env绑定 →delegate_-OnAttach(env)Detach顺序与 Attach 镜像先delegate_-OnDetach(env)再RemoveLoader()最后proxy_-Detach()NapiEnvironment::From(Napi::Env env)通过env.GetInstanceDataNapiEnvironment(kEnvClassID)反查环境实例kEnvClassID使用reinterpret_castuint64_t(kEnvClassID)的地址作为唯一 ID避免魔法数字冲突。三、NapiRuntimeProxy跨引擎的运行时胶水3.1 接口抽象NapiRuntimeProxyInterface 定义了引擎无关的最小契约class NapiRuntimeProxyInterface { public: virtual void Attach() 0; virtual void Detach() 0; virtual Napi::Env Env() 0; virtual void SetJSRuntime(base::UnsafeWeakPtrRuntime runtime) 0; virtual base::UnsafeWeakPtrRuntime GetJSRuntime() 0; virtual void SetupLoader() 0; virtual void RemoveLoader() 0; virtual void SetUncaughtExceptionHandler() 0; };注意js_runtime_使用UnsafeWeakPtrRuntime持有 JS 运行时而非强引用——这是避免 runtime 生命周期循环依赖的关键设计。3.2 多后端工厂与运行时创建NapiRuntimeProxy::Create 依据runtime.type()分发到不同后端JSRuntimeType::v8通过NapiRuntimeProxyV8Factory工厂创建。工厂接口注释napi_runtime_proxy_v8_factory.h说明它「Used by DevTool and dynamic v8 to set a factory from another shared library (so as to avoid bloating liblynx.so)」——即由 DevTool 或动态 V8 从另一个共享库注入工厂避免膨胀 liblynx.soJSRuntimeType::jsc仅OS_IOS || OS_OSX平台可用直接构造NapiRuntimeProxyJSCJSRuntimeType::quickjs从QuickjsRuntime取出共享上下文构造NapiRuntimeProxyQuickjsJSRuntimeType::jsvm通过NapiRuntimeProxyJSVMFactory工厂创建。对应的导出注册接口供外部注入LYNX_EXPORT void RegisterV8RuntimeProxyFactory(NapiRuntimeProxyV8Factory* factory); LYNX_EXPORT void RegisterJSVMRuntimeProxyFactory(NapiRuntimeProxyJSVMFactory* factory);引擎专属实现文件按命名清晰分离napi_runtime_proxy_v8.cc、napi_runtime_proxy_quickjs.cc、napi_runtime_proxy_jsc.cc、napi_runtime_proxy_jsvm.cc与 AGENTS.md 中「backend-specific proxy specializations should stay in their dedicated files」的编辑规则一一对应。3.3 Loader 机制与共享上下文兼容SetupLoader实现见揭示了几条关键细节默认 Loader 名称为napiLoaderOnRT runtimeIdis_safe_napi_时使用固定名__lynxNapiLoader通过napi_setup_loader(env_, loader_.c_str())注册并在全局对象上挂载对单上下文runtime-getGroupId() -1做兼容额外把__lynxNapiLoader指向同一 Loader通过napiSharedMarker标记检测是否处于共享上下文shared context这是多 App/多实例场景下的防冲突手段RemoveLoader在销毁时删除对应全局键防止内存泄漏。3.4 未捕获异常处理SetUncaughtExceptionHandler通过binding::CallbackHelper::SetUncaughtExceptionHandler(env_, ReportError)注册。ReportErrornapi_runtime_proxy.cc#L152-L182会读取global.currentAppId与global.multiApps定位当前 App 代理再调用lynx.reportError上报USER_RUNTIME_ERROR若 App 已销毁app_proxy为 null/undefined则静默返回。四、安全沙箱RestrictedNapiRuntimeProxyDecoratorRestrictedNapiRuntimeProxyDecorator 是NapiRuntimeProxyInterface的装饰器为外部用户提供受限的napi_env——禁用napi_run_script与napi_get_global防止用户注入的模块破坏 Lynx 脚本运行时稳定性。实现要点napi_runtime_proxy.cc#L284-L337SetupLoader先保存原始napi_get_global函数指针然后把raw_env-napi_run_script与raw_env-napi_get_global替换为LynxHookedNapiRunScript/LynxHookedNapiGetGlobal这两个钩子函数直接抛错napi_run_script is not allowed in lynx module. napi_get_global is not allowed in lynx module.受限 Loader 名为napiRestrictedLoader runtimeId挂载一个含load方法的 exports 对象LoadRestrictedModule通过napi_find_module查找注册模块并用RestrictedModuleRegistry存于napi_env的 InstanceData做已加载模块缓存避免重复初始化。五、编辑规则与常见回归症状AGENTS.md 核心约束根据 AGENTS.md 的 Edit Rules维护该目录时必须遵守保持后端无关环境与 runtime-proxy 逻辑应尽可能与具体引擎解耦引擎专属的 proxy 特化必须放在各自专用文件napi_runtime_proxy_{v8,quickjs,jsc,jsvm}.cc谨慎处理生命周期特别小心 lifetime、runtime ownership如UnsafeWeakPtrRuntime的持有方式与跨引擎能力差异不同引擎对 NAPI 支持度不同。文档列出的两类常见回归症状正是评审和自测时的重点观察项NAPI 模块在一个引擎中正常、换引擎后失败通常是 proxy 改动破坏了后端无关性或依赖了某个引擎特有的 NAPI 行为环境创建/销毁仅在集成流程中回归孤立调用点无异常说明问题出在 Attach/Detach 的生命周期顺序如 Loader 未清理、InstanceData 残留或线程切换路径上需要结合集成测试排查。六、验证方式runtime_tests_exec 与单元测试AGENTS.md 声明该目录没有独立声明的可执行目标验证统一通过runtime_tests_exec完成。该目标定义在 core/runtime/BUILD.gn聚合:runtime_testset下全部 runtime 相关测试集。针对 NAPI 环境本身目录内置了专用单测 napi_environment_unittest.cc通过 QuickJS 上下文构造NapiRuntimeProxyQuickjs并驱动真实NapiEnvironment覆盖三类典型场景BasicScriptingTestAttach 后验证脚本执行env_.RunScript(321)返回 321、全局变量读写x 42、函数调用链路LoadModuleTest自定义TestDelegate在OnAttach中调用TestModule::OnLoad注入构造器验证new TestElement(test)、getContext缓存复用ctx ctx1、testPlusOne(41) 42等模块逻辑。若 NAPI 环境契约发生变更AGENTS.md 还建议同时检查附近 runtime common 与 value-wrapper 的测试覆盖——这提示 NAPI 环境与 value_wrapper 之间存在联动依赖。七、shim 层跨平台 NAPI 头文件统一shim/README.md 解释了目录内 shim 子目录的由来Android 上直接依赖 NAPI 源码而 iOS 上依赖发布的 NAPI Pod这一差异导致两边无法包含同一份头文件。shim 层shim_napi_env_jsc.h、shim_napi_env_quickjs.h、shim_napi_env_v8.h正是为了在 Lynx 代码中统一包含同一头文件而引入的适配层。该 README 同时注明「This should be fixed soon as Android is adopting libc_shared.so」说明这是一个临时的兼容性方案。八、小结core/runtime/common/napi是 Lynx 多引擎 NAPI 架构的枢纽NapiEnvironment提供统一的环境门面与模块生命周期NapiRuntimeProxy抽象出跨 V8/QuickJS/JSC/JSVM 的运行时胶水RestrictedNapiRuntimeProxyDecorator通过 hooknapi_run_script/napi_get_global构建安全沙箱。在修改该目录时请始终牢记 AGENTS.md 的三条铁律——后端无关、生命周期谨慎、跨引擎差异警觉——并通过runtime_tests_exec与目录内 QuickJS 单测验证改动。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考