wagmi 中 @wagmi/solid 的 walletConnect Connector：配置、参数与源码级实现解析-北京尧图网络

wagmi 中 wagmi/solid 的 walletConnect Connector配置、参数与源码级实现解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇技术指南以 wagmi 仓库中wagmi/solid的 WalletConnect connector 官方文档为核心完整覆盖其安装、导入、createConfig集成方式以及全部配置参数projectId、isNewChainsStale、qrModalOptions、showQrModal等。结合 packages/connectors/src/walletConnect.ts 的源码实现你将理解 Wagmi 是如何在内部托管walletconnect/ethereum-provider的初始化、链授权stale chains判定、RPC 映射与事件桥接的从而能正确地在 Solid 应用中接入 WalletConnect v2 并处理常见连接问题。定位与适用场景WalletConnect 是跨应用、跨设备的钱包连接标准DApp 通过二维码配对用户可在移动端钱包或桌面钱包中授权账户与链之后通过中继服务relay与 DApp 双向通信。在 wagmi 中它被封装为一个标准的Connector与injected、metaMask、coinbaseWallet等并列统一接入createConfig的连接/切换链/授权体系。在 Solid 技术栈中connector 的入口来自wagmi/solid/connectors子路径。从 packages/solid/src/exports/connectors.ts 可见该子路径直接再导出wagmi/connectors的全部 connector 实现对应的导出测试 packages/solid/src/exports/connectors.test.ts 的快照中也确认walletConnect在导出列表中与baseAccount、metaMask、injected等并列。connector 的实际实现位于 core 生态包 packages/connectors/src/walletConnect.tswagmi/solid、wagmiReact与wagmi/vue等框架包共用同一份实现因此本文的参数说明与底层行为对各框架一致。安装WalletConnect connector 依赖外部包walletconnect/ethereum-provider它被声明为可选 peer dependency见 packages/connectors/package.json 中walletconnect/ethereum-provider: ^2.21.1及peerDependenciesMeta中的optional: true。也就是说只有当你真正使用 WalletConnect 时才需要安装它源码中对它使用了动态import()并标注 webpack/turbopack 的 optional 语义未安装时不会影响其他 connector 的打包。安装命令以 pnpm 为例npm / yarn / bun 同理pnpm add walletconnect/ethereum-provider^2.21.1说明文档模板中的x.y.z占位版本由构建脚本自动同步为仓库 lockfile 中的实际版本当前仓库中为^2.21.1。导入import { walletConnect } from wagmi/solid/connectors类型层面参数类型WalletConnectParameters同样从该子路径导入import { type WalletConnectParameters } from wagmi/solid/connectors该类型在 packages/connectors/src/walletConnect.ts 中定义为以EthereumProvider.init的完整参数为基础剔除了由 Wagmi 内部托管的chains、optionalChains、rpcMap、methods、events等字段再额外增加isNewChainsStale选项并将showQrModal放宽为可部分省略的精确可选字段。这解释了为什么文档强调部分选项已被 Wagmi 内部接管而省略。基础用法接入 createConfigimport { createConfig, http } from wagmi/solid import { mainnet, sepolia } from wagmi/solid/chains import { walletConnect } from wagmi/solid/connectors export const config createConfig({ chains: [mainnet, sepolia], connectors: [ walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, }), ], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })仓库自带的 Solid 示例应用 playgrounds/vite-solid/src/wagmi.ts 展示了更完整的真实用法同时挂载walletConnect、baseAccount、metaMask三个 connector并从环境变量注入 projectIdimport { createConfig, http } from wagmi/solid import { celo, mainnet, optimism, sepolia } from wagmi/solid/chains import { baseAccount, metaMask, walletConnect } from wagmi/solid/connectors export const config createConfig({ chains: [mainnet, sepolia, optimism, celo], connectors: [ walletConnect({ projectId: import.meta.env.VITE_WC_PROJECT_ID, }), baseAccount(), metaMask(), ], transports: { [mainnet.id]: http(), [sepolia.id]: http(), [optimism.id]: http(), [celo.id]: http(), }, })随后在组件树中通过WagmiProvider见 packages/solid/src/context.ts注入该 config其内部经Hydrate完成状态恢复与重连之后即可使用useConnect等 primitives 触发 WalletConnect 连接。参数详解以下参数完整继承自官方文档 site/solid/api/connectors/walletConnect.md其正文通过include复用共享文档 site/shared/connectors/walletConnect.md并结合源码说明各参数的实际作用点。projectId必填类型string说明WalletConnect Cloud 项目标识符需从 WalletConnect 开发者仪表板获取是初始化EthereumProvider的必备凭据。import { walletConnect } from wagmi/solid/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })customStoragePrefix类型string | undefined自wagmi/solid 0.0.40支持说明自定义 provider 状态持久化的存储前缀。当同一浏览器环境中存在多个使用 WalletConnect 的站点/应用时可用不同前缀隔离本地持久化的会话数据。const connector walletConnect({ customStoragePrefix: wagmi, projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })该参数原样透传给EthereumProvider.init在 getProvider 的初始化逻辑中随...parameters展开传入。isNewChainsStale类型boolean | undefined默认值true说明当向已有 connector 的chains列表中新增一条链时该标志决定这条新链是否被视为过期链stale chain。所谓过期链是指用户在 WalletConnect 会话中尚未与之建立关系未批准或未拒绝的链。const connector walletConnect({ isNewChainsStale: true, projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })这是整个 connector 中最需要理解的行为其背景是WalletConnect v1 支持动态切换链而 v2 要求用户在会话建立时预先批准一组链。当 dapp 后续修改了配置的链列表就会出现用户会话中没有新链授权的不一致状态此标志就是处理该不一致的策略开关true默认新链被视为过期链。若用户尚未在新链上建立关系connector 会在 dapp 自动重连auto-connect时主动断开当前会话要求用户重新连接从而在钱包侧重新验证并批准新链。这是默认行为目的是避免在用户不知情的情况下切链时抛出令人困惑的错误。false新链被视为潜在有效链。即使用户尚未批准该链wagmi 也会自动重连成功代价是当用户尝试切换到这条未批准的链时会抛出错误。适用于 dapp 频繁变更配置链列表、不希望 auto-connect 时断开用户的场景——此时必须自行捕获该错误并提示用户重新连接以批准新链。源码中该行为由isChainsStale()方法落地packages/connectors/src/walletConnect.ts它将当前config.chains与持久化在walletConnect.requestedChains存储键中的曾请求过的链 ID逐一比对只要存在配置链不在已请求集合中即判定为 stale且若 WalletConnect 会话的eip155命名空间与新配置链毫无交集则直接返回 false 不判定为过期。isNewChainsStale为false时该方法恒返回false。这一判定在connect()与isAuthorized()两处生效前者在 stale 且存在活跃会话时先provider.disconnect()再重新发起带全部链的provider.connect({ optionalChains })后者在 stale 时同样断开并返回未授权。metadata类型CoreTypes.Metadata | undefined说明发起连接请求的应用元数据会展示在钱包侧的授权界面中建议包含应用名、描述与网址。const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, metadata: { name: Example, description: Example website, url: https://example.com, }, })projectId 之外的传输相关参数relayUrl类型string | undefined默认值wss://relay.walletconnect.com说明WalletConnect 中继 WebSocket 地址。const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, relayUrl: wss://relay.walletconnect.org, })storageOptions类型KeyValueStorageOptions | undefined说明provider 本地存储的行为选项。const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, storageOptions: {}, })二维码弹窗相关参数showQrModal类型boolean | undefined默认值true说明调用connector.connect()时是否展示官方二维码弹窗。const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, showQrModal: true, })官方提示可以将其关闭并监听message事件payload 为{ type: display_uri; data: string }来自行渲染二维码。源码印证了这条链路的完整实现provider 的display_uri事件在connect()内被监听经onDisplayUri回调转发为config.emitter.emit(message, { type: display_uri, data: uri })在框架层即可通过订阅 config 的message事件拿到 URI连接完成后监听器会被移除。qrModalOptions类型QrModalOptions | undefined说明官方二维码弹窗的渲染选项例如主题模式。const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, qrModalOptions: { themeMode: dark, }, })更多选项请查阅walletconnect/ethereum-provider的上游文档WalletConnect 官方仓库。源码纵深Wagmi 内部托管了哪些细节文档中部分选项由 Wagmi 内部托管一句具体含义可以从 packages/connectors/src/walletConnect.ts 中getProvider()的初始化代码得到完整验证return await EthereumProvider.init({ ...parameters, disableProviderPing: true, optionalChains, // 来自 config.chains projectId: parameters.projectId, rpcMap: Object.fromEntries( config.chains.map((chain) { const [url] extractRpcUrls({ chain, transports: config.transports }) return [chain.id, url] }), ), showQrModal: parameters.showQrModal ?? true, })几个关键设计点optionalChains与rpcMap由 config 自动派生。用户不需要也不应该在参数里手写链列表与 RPC 映射所有config.chains的 ID 会进入optionalChains每条链的 RPC URL 则通过extractRpcUrls({ chain, transports: config.transports })从你配置在该链上的 transport如http()中取出。这就是基础用法示例中transports字段存在的意义之一——它同时服务于 wagmi 的读取/调用与 WalletConnect provider 的rpcMap。disableProviderPing: true关闭 provider 初始化时的周期性 ping减少无谓的中继往返。Provider 单例与惰性初始化EthereumProvider是 peer 依赖首次getProvider()才动态import并init且用providerPromise防止并发重复初始化events.setMaxListeners(Number.POSITIVE_INFINITY)避免 Node 环境下监听器告警。connect()的完整编排确定目标链未指定时优先取持久化 state 中仍被支持的chainId否则取第一条配置链→ 检测 stale 并在需要时断开旧会话 → 以目标链其余所有配置链作为optionalChains发起provider.connect→provider.enable()取账户 → 若指定了chainId且当前链不符则尝试switchChain对钱包不支持wallet_addEthereumChain的拒绝做了容错回退到当前链→ 挂载accountsChanged/chainChanged/disconnect/session_delete监听统一转发到 wagmi 的emitterconnect/change/disconnect事件供 Solid 的状态层响应。链切换与自动添加链switchChain()先尝试wallet_switchEthereumChain并等待 emitter 的change事件确认切换若失败链未存在于钱包则以chain配置中的name、rpcUrls、nativeCurrency、默认区块浏览器 URL 等拼装wallet_addEthereumChain参数请求添加用户拒绝时抛UserRejectedRequestError。会话删除即断开session_delete事件例如用户在钱包侧主动删除 dapp会触发onDisconnect清理监听器、清空requestedChains存储并发出 wagmi 的disconnect事件。错误处理与常见现象用户在钱包侧拒绝配对或取消请求时connect()会将匹配user rejected/connection request reset的底层错误统一转换为 viem 的UserRejectedRequestError便于上层做一致的失败提示。账户被钱包侧清除accountsChanged收到空数组会直接触发onDisconnect。若 dapp 修改了config.chains而用户会话未覆盖新链按前述isNewChainsStale的语义可能出现自动重连后连接被断开的现象——这是默认策略下的预期行为而非 bug如需避免可显式设置isNewChainsStale: false并自行处理后续切链错误。参考路径汇总内容相对路径Solid 框架 walletConnect 文档页本文档源site/solid/api/connectors/walletConnect.md共享 connector 文档正文include目标site/shared/connectors/walletConnect.mdconnector 核心实现参数类型、connect/switchChain/isChainsStalepackages/connectors/src/walletConnect.ts依赖声明walletconnect/ethereum-provider可选 peerpackages/connectors/package.jsonwagmi/solid/connectors子路径导出packages/solid/src/exports/connectors.tsSolid 示例应用多 connector 环境变量 projectIdplaygrounds/vite-solid/src/wagmi.tsWagmiProvider / 状态注入packages/solid/src/context.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

wagmi 中 @wagmi/solid 的 walletConnect Connector：配置、参数与源码级实现解析

相关推荐

Warp 发布说明自动起草全流程：基于 Towncrier 片段的 GitHub Release Notes 生成指南

IDEA社区版安装配置全流程：JDK环境到Java项目实战

WSL2 报错 HCS_E_HYPERV_NOT_INSTALLED 修复指南

更多资讯

LeetCode 39题：回溯算法解组合总和问题

2026年9月幕墙楼顶发光字厂家电话，字工场装配式工艺施工!

UniApp移动应用智能更新方案设计与实践

Java Web开发入门：Servlet环境搭建与实战指南

CSS字体样式全攻略：从基础避坑到渐变描边与实战速查

DTU技术规范核心约束与工程落地验证指南

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？