fhEVM `@fhevm/sdk` 运行时兼容性完全指南:多线程、单线程与边缘运行时支持矩阵

发布时间:2026/9/13 19:38:02

fhEVM `@fhevm/sdk` 运行时兼容性完全指南:多线程、单线程与边缘运行时支持矩阵 fhEVMfhevm/sdk运行时兼容性完全指南多线程、单线程与边缘运行时支持矩阵【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本指南以 sdk/js-sdk/docs/runtime-compatibility.md 为核心系统讲解fhevm/sdk在浏览器、Node.js、Bun、Deno、Electron 与 Next.jsCSR/SSR/Edge等环境中的运行前提、线程能力判定与降级策略。读完你将掌握为什么“单线程在任何能编译 WASM 的环境都能跑”、多线程到底依赖哪些底层能力SharedArrayBuffer Worker 后端、以及为什么 Vercel Edge / Cloudflare Workers 无法在隔离区内直接运行 SDK——并能在自己的部署里做出正确的工程取舍。一、SDK 运行环境的三大能力前提fhevm/sdk内部会加载两个 WebAssembly 模块TFHE加密可多线程与TKMS解密始终轻量、单线程。因此一个环境是否支持 SDK最终取决于以下三项能力WASM 编译能力——运行时必须允许从字节构建 WebAssembly 模块WebAssembly.compile。如果 SDK 无法编译 WASM则完全无法运行这是硬性前提。解压能力——内嵌的 WASM 以 gzip 压缩存放。SDK 优先使用平台原生DecompressionStream否则回退到内置的纯 JS inflater兼容旧浏览器与部分运行时。因此解压永远不会成为硬性阻塞。线程能力仅 TFHE 多线程需要——多线程 TFHE 需要同时具备SharedArrayBuffer和 worker 后端WebWorker或node:worker_threads。二者缺一SDK 会优雅降级为单线程单线程永远可用它不需要 worker。核心结论凡是能编译 WASM 的环境单线程模式一定可用多线程只是需要额外线程能力支撑的性能优化。二、支持矩阵权威速查表下表是 runtime-compatibility.md 中支持矩阵的完整呈现。其中“when cross-origin isolated”指页面通过Cross-Origin-Opener-Policy: same-origin与Cross-Origin-Embedder-Policy: require-corp两个响应头服务使得crossOriginIsolated true且SharedArrayBuffer可用。环境SDK 运行ST多线程MTMT 在此需要什么备注Browser客户端✅✅ 跨源隔离时COOP/COEP 头 →SharedArrayBuffer Web Workers零配置。无 COOP/COEP → 降级为 ST。Browser — 旧版Firefox 113、Safari 16.4✅✅ 跨源隔离时同上无DecompressionStream→ SDK 使用纯 JS inflater。Electron沙箱化 renderer✅✅ 跨源隔离时Web Worker沙箱 renderer 中无worker_threadsSDK 自动选择 Web Worker 后端。Node.js脚本、后端、长驻服务✅✅node:worker_threadsSharedArrayBuffer始终可用无需 COOP/COEP——Node 中 SAB 恒存在。Bun✅✅worker_threads为与 Node 保持行为一致强制走 Node worker 后端。Deno✅✅ 隔离时Web Worker SharedArrayBufferWeb 标准后端。Next.js — CSR客户端组件任意 server runtime✅✅ 跨源隔离时浏览器SharedArrayBuffer Web WorkersSDK 运行在浏览器server runtime 只提供外壳。Next.js — SSRNode runtime服务端组件✅✅node:worker_threadsCOOP/COEP 服务端无关需要 bundler 的node:导入提示见“Bundlers”节。Next.js — SSREdge runtime服务端组件❌❌—不支持。见下文“Edge”。Next.js — Edge route CSRruntimeedge路由上的客户端组件✅✅ 跨源隔离时浏览器SharedArrayBuffer Web Workers支持——SDK 在客户端运行edge isolate 从不接触 WASM。Vercel Edge / Cloudflare Workers在 isolate内运行 SDK❌❌—不支持。见下文“Edge”。图例✅ 支持 · ❌ 不支持 · “when cross-origin isolated” 页面以Cross-Origin-Opener-Policy: same-originCross-Origin-Embedder-Policy: require-corp服务即crossOriginIsolated true且SharedArrayBuffer可用。从源码看这套矩阵正是 environment.ts 中基于能力探测而非 UA 字符串的环境判定的直接结果isNodeLike()检查process.versions.nodeisBrowserLike()要求存在location.href与addEventListener而 Vercel Edge、Cloudflare Workers、Next.js edge 既非 Node 也非浏览器探测返回安全值false/undefined调用方自然回退到 Web 标准 API。三、SSR 与 CSR 的本质区别元框架场景对于 Next.js 这类元框架SDK 代码在哪里执行比它位于哪条路由更重要CSR——SDK 运行在客户端组件中水合后在浏览器里执行。这是正常且完全受支持的路径。server runtimeNode或Edge只渲染 HTML 外壳从不编译 WASM因此即使是 edge 渲染的路由也可用只要 SDK 在客户端使用。SSR——SDK 运行在服务端组件中在服务端渲染期间执行。Node runtime 支持Edge runtime 不支持。因此“edge”并非一概不支持edge CSR 受支持edge SSR 不受支持。这是使用 Next.js 部署 fhEVM dApp 时最重要的工程判断之一。四、为什么 Edge 运行时服务端跑不了 SDK在 edge isolate 内部Vercel Edge、Cloudflare Workers、Next.jsruntimeedge服务端组件运行 SDK 会失败原因是三个相互独立的限制禁止动态 WASM 编译。Edge isolate 禁止运行时生成代码包括从字节调用WebAssembly.compile/instantiate。SDK 恰恰是从字节编译模块因此被拒绝。Next.jsdev模式在 Node 上模拟 Edge 且仅发出警告——DynamicWasmCodeGenerationWarning——所以本地看似能跑生产环境却会失败。没有SharedArrayBuffer。Edge isolate 不暴露 SAB因此supportsThreads为false→ 无论如何 MT 都不可能。代码体积限制。TFHE 模块有数 MB见下文通常超过 edge 的 bundle 大小上限。推荐方案在 edge 部署中从客户端组件CSR使用 SDK——edge runtime 负责服务页面浏览器负责运行 SDK。关于 TFHE 模块的体积可在 architecture.md 中找到佐证encrypt 模块的 TFHE WASMZK proof 生成约4.9 MB而 decrypt 模块的 TKMS WASM份额重建约600 KB。这也是 edge 环境代码体积限制被击穿的直接原因。五、Bundlers为什么消费者无需任何操作SDK 通过动态import()加载 Node 内置模块worker_threads、fs等并用环境检查做守卫。打包器必须被告知不要对这些导入做静态分析各自通过自己的 magic comment 实现——SDK 内置了全部三种// sdk/js-sdk/src/core/base/environment.ts 中的 _importNodeModule const id node:${name}; return (await import(/* vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ id)) as mod;vite-ignore—— VitewebpackIgnore: true—— webpackturbopackIgnore: true—— TurbopackNext.js。没有它Turbopack 无法分析由参数派生的模块说明符无法把node:内置模块当作候选打包会把调用替换成抛Cannot find module unknown的 stub——这曾静默禁用 Next 服务端组件中的 Nodeworker_threads后端→ TFHE 变为单线程。三个注释各自指示对应 bundler 发出原生import()由运行时解析在浏览器中该调用会抛错并被捕获返回undefined。SDK 消费者无需任何操作此处仅为完整说明。六、解压回退机制内嵌 WASM 是 gzip 压缩的。SDK 探测是否存在可用的DecompressionStream——注意它通过实际构造一个实例来探测因为仅做typeof检查不够部分运行时典型如 Next.js Edge Runtime暴露的是构造即抛错的 stub仅凭存在性判断是假阳性会在编译路径深处崩溃。相关实现在 environment.ts 的supportsDecompressionStream()export function supportsDecompressionStream(): boolean { if (_decompressionStreamSupported undefined) { if (typeof DecompressionStream ! function || typeof Blob ! function) { _decompressionStreamSupported false; } else { try { // 构造即探测——Next.js Edge stub 在这里抛错真实实现不会。 const probe new DecompressionStream(gzip); void probe; _decompressionStreamSupported true; } catch { _decompressionStreamSupported false; } } } return _decompressionStreamSupported; }当探测失败时SDK 回退到内置、零依赖的纯 JS inflater从而在旧浏览器Firefox 113、Safari 16.4及其他缺少可用DecompressionStream的运行时中依然能解压小体积的压缩载荷——无需消费者做任何事。七、线程降级源码级原理多线程并非“想开就开”。在 init-p.ts 的_resolveThreadConfig()中完整的降级逻辑如下线程数来源numberOfThreads未配置时取navigator.hardwareConcurrencynavigator缺失部分 edge 运行时、Node 21时降为 0单线程。numberOfThreads必须是非负整数否则直接抛错避免把调用者的错误静默抹平。SAB 探测线程数 0 时通过wasm-feature-detect的threads()探测SharedArrayBuffer浏览器中 SAB 依赖 COOP/COEP 头。探测失败则打印警告并降级单线程This browser does not support threads. Verify that your server returns correct headers: Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corpworker 可用性auto模式下若线程可用但 blob/eval worker 不可用CSP 禁止blob:worker、Node 的--disallow-code-generation-from-strings等同样降级单线程。初始化非单线程时才调用tfheLib.initThreadPool(numberOfThreads)启动 worker 池单线程直接跳过。SDK 从不因线程问题抛错——缺少头或环境不支持线程时只记录警告并透明降级。这也印证了文档中的结论单线程总可用不需要 workerWASM 仍通过 URL 或内嵌 base64 加载。与之配套的 worker 后端选择在 isomorphicWorker.ts 的resolveWorkerApi()中运行时Web APINode API选中浏览器window / web worker有无web沙箱化 Electron renderer有无webNode.js无有nodejsdomVitest无有nodeDeno有有webBun有有node强制与 Node 保持一致注意沙箱化 Electron renderer 虽process.versions.node已设置但node:worker_threads不可用——由于 Web 优先策略它会自动走 Web Worker 后端这正是支持矩阵中“Electron 沙箱 renderer”一行的实现依据。八、实战配置建议1. 浏览器启用多线程设置 COOP/COEP 头由托管应用的服务器设置Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp缺头时浏览器禁用SharedArrayBufferSDK 自动回退单线程见 runtime-configuration.md。2. 强制单线程为最大化兼容性、或无法设置响应头时显式关闭线程import { setFhevmRuntimeConfig } from fhevm/sdk/ethers; // 或from fhevm/sdk/viem setFhevmRuntimeConfig({ singleThread: true });注意setFhevmRuntimeConfig按适配器隔离——fhevm/sdk/ethers与fhevm/sdk/viem各自持有独立配置必须从你创建 client 的同一适配器导入调用若同时使用两个适配器需分别配置。它在创建任何 client 之前调用一次重复调用相同配置为 no-op不同配置则抛错。3. 需要性能时显式指定线程数setFhevmRuntimeConfig({ numberOfThreads: 8 }); const client createFhevmClient({ chain: sepolia, provider }); await client.init(); // 现在编译 WASMnumberOfThreads: 0同样强制单线程。构造 client 不做任何 I/OWASM 编译的时机由你通过client.init()/client.ready掌控。4. Edge 部署的铁律若使用 Vercel Edge / Cloudflare Workers / Next.jsruntimeedgeSDK 只能从客户端组件CSR使用。edge 运行时服务页面浏览器运行 SDK——这是官方推荐且在矩阵中受支持的唯一 edge 姿势。5. 关注 WASM 体积与加载TFHE WASM 约 4.9 MB、TKMS 约 600 KB。加密客户端createFhevmEncryptClient只扩展 encrypt 模块bundler 不会打入 decrypt 的 WASM——按需选择 client 工厂即可控制打包体积。WASM/worker 资产的托管、locateFile、wasmAssetLoadMode与版本固定moduleVersions等加载细节详见 runtime-configuration.md。九、相关文档运行时配置 —— 线程、COOP/COEP 与 WASM 资产加载的完整配置项。Clients —— 加载这些 WASM 模块的 client 工厂。架构 —— loader 背后的运行时与模块设计。环境能力探测源码 —— 运行时识别、Node 内置模块动态导入与DecompressionStream探测。同构 Worker 源码 —— worker 后端选择矩阵与 blob/eval worker 冒烟测试。TFHE 模块初始化源码 —— 线程配置解析、SAB 探测与降级策略。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/13 19:33:02

Simulink实现CDMA系统仿真:扩频、同步与多用户检测全流程

简介:本资源是一套基于MATLAB Simulink的CDMA系统仿真工程包,面向通信工程专业本科生、研究生及无线通信方向初学者,用于深入理解码分多址原理、扩频通信机制与多用户干扰建模等核心知识点。压缩包共140个文件,包含15个Simulink模…

2026/9/13 19:33:02

GoFr 自动渲染 OpenAPI / Swagger 交互式 API 文档

GoFr 自动渲染 OpenAPI / Swagger 交互式 API 文档 【免费下载链接】gofr An opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability. 项目地址: https://gitcode.com/GitHub_Trending/go/gofr Go…

2026/9/13 20:33:06

电力系统潮流计算与牛顿-拉夫逊算法实现详解

1. 电力系统潮流计算与牛顿-拉夫逊算法解析电力系统潮流计算是电力网络分析中最基础也最重要的计算任务之一。简单来说,它就像给电网做一次全面的"体检"——通过计算电网中各节点的电压幅值、相角以及支路功率分布,来评估电网的运行状态是否健…

2026/9/13 20:33:06

3分钟做出专业演示视频:OpenScreen 完整上手指南

3分钟做出专业演示视频:OpenScreen 完整上手指南 【免费下载链接】openscreen Create stunning demos for free. Open-source, no subscriptions, no watermarks, and free for commercial use. An alternative to Screen Studio. 项目地址: https://gitcode.com/…

2026/9/13 20:33:06

C++多线程编程从基础到实战:std::thread、锁与线程池详解

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/13 20:33:06

DB-GPT 接入 DuckDB 数据源完整指南:安装、配置与源码解析

DB-GPT 接入 DuckDB 数据源完整指南:安装、配置与源码解析 【免费下载链接】DB-GPT open-source agentic AI data assistant for the next generation of AI Data products. 项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT DuckDB 是一款高性能的…

2026/9/13 0:01:16

拯救者Y7000黑屏故障排查与维修实战指南

1. 项目概述:一台黑屏的拯救者Y7000,到底卡在哪一步? 联想拯救者Y7000系列笔记本,从2018年第一代搭载i5-8300H开始,到后来的i7-9750H、i7-10750H、i5-11400H,再到2023年款的R7-7840HS,它始终是学…

2026/9/13 0:01:16

拯救者Y7000黑屏故障排查与维修实战指南

1. 项目概述:一台黑屏的拯救者Y7000,到底卡在哪一步? 联想拯救者Y7000系列笔记本,从2018年第一代搭载i5-8300H开始,到后来的i7-9750H、i7-10750H、i5-11400H,再到2023年款的R7-7840HS,它始终是学…

2026/9/12 6:29:36

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/12 14:32:17

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/13 11:18:28

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码