wagmi Vue 中的 WalletConnect 连接器配置参数与底层实现深度解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本指南以 site/vue/api/connectors/walletConnect.md 及其共享文档主体为核心讲解在wagmi/vue中接入 WalletConnect 连接器的完整方案。你将掌握walletConnect()的安装与导入方式、全部可配置参数projectId、metadata、isNewChainsStale、showQrModal等的语义与默认值并通过 packages/connectors/src/walletConnect.ts 的源码解读理解其连接、断连、切换链与链失效stale chain判定的底层机制。walletConnect 连接器概览walletConnect是 wagmi 为 WalletConnect 协议提供的官方连接器底层基于walletconnect/ethereum-provider实现。它是wagmi/connectors包导出的连接器之一并且被wagmi/vue/connectors入口完整转发连接器实现与类型定义位于 packages/connectors/src/walletConnect.ts包级导出声明位于 packages/connectors/src/exports/index.tsVue 框架入口通过 packages/vue/src/exports/connectors.ts 的export * from wagmi/connectors对外暴露从源码结构看walletConnect是一个工厂函数调用后返回一个符合Connector契约的createConnector配置对象其id固定为walletConnectname为WalletConnecttype为walletConnect。在 packages/connectors/src/walletConnect.test.ts 的测试中setup用例会验证connector.name WalletConnect并断言connect参数包含可选的pairingTopic字段。安装与导入安装依赖walletconnect/ethereum-provider是walletConnect连接器必需的第三方依赖。在 packages/connectors/package.json 中它被声明为可选 peer dependencywalletconnect/ethereum-provider: ^2.21.1因此需要你显式安装# pnpm pnpm add walletconnect/ethereum-provider^2.21.1 # npm npm install walletconnect/ethereum-provider^2.21.1 # yarn yarn add walletconnect/ethereum-provider^2.21.1 # bun bun add walletconnect/ethereum-provider^2.21.1需要说明的是该依赖是可选的wagmi 在getProvider()内部通过动态import(walletconnect/ethereum-provider)按需加载见下文源码解析未安装时仅在使用该连接器时才会失败。导入连接器在 Vue 项目中统一从wagmi/vue/connectors入口导入import { walletConnect } from wagmi/vue/connectors基本用法在createConfig的connectors数组中传入walletConnect()其中projectId是唯一必填参数import { createConfig, http } from wagmi/vue import { mainnet, sepolia } from wagmi/vue/chains import { walletConnect } from wagmi/vue/connectors export const config createConfig({ chains: [mainnet, sepolia], connectors: [ walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, }), ], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })随后通过useConnect()、useDisconnect()等组合式函数即可驱动连接流程。需要注意的是walletConnect()接收的类型为WalletConnectParameters源码中定义如下见 packages/connectors/src/walletConnect.ts显式声明了 wagmi 自管的字段isNewChainsStale从EthereumProviderOptions中剔除 wagmi 内部接管的部分chains、events、optionalChains、optionalEvents、optionalMethods、methods、rpcMap、showQrModalshowQrModal又被重新以可选形式开放见下文其余所有EthereumProvider.init选项原样透传。这意味着除了本文列举的参数walletconnect/ethereum-provider支持的其他初始化选项如storageOptions、relayUrl等同样可以直接传入。参数详解projectId必填类型string说明WalletConnect Cloud 项目标识符在 WalletConnect 控制台创建项目后获取。这是建立 WalletConnect v2 会话的必要凭据缺少它连接器无法初始化 provider。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, // [!code focus] })metadata类型CoreTypes.Metadata | undefined说明向钱包端展示的 dapp 元信息应用名、描述、URL、图标等会出现在钱包的授权确认界面。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, metadata: { // [!code focus] name: Example, // [!code focus] description: Example website, // [!code focus] url: https://example.com, // [!code focus] }, // [!code focus] })isNewChainsStale类型boolean | undefined默认值true说明控制“新加入配置的链”是否被判定为 stale失效。所谓 stale 链指 WalletConnect 会话中尚未与用户建立关系未批准/未拒绝的链。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ isNewChainsStale: true, // [!code focus] projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })这一参数需要结合 WalletConnect v2 的机制理解v1 支持动态切换任意链而 v2 要求用户在会话建立时预先批准一组链。具体行为如下true默认新链视为 stale。若用户在该链上尚未批准/拒绝连接器会在 dapp 自动重连时主动断开会话用户必须重新连接重新校验链才能批准新链。这是默认行为目的是避免切换链时抛出难以理解的错误例如用户根本不知道需要重新连接除非 dapp 自行处理这类错误。false新链视为潜在有效链。即使会话中尚未建立关系wagmi 也能成功自动重连代价是当钱包不支持动态会话更新时切换到未批准链会抛错。适合“dapp 频繁修改链配置、且不希望自动重连时踢掉用户”的场景此时 dapp 必须自行捕获切换错误并引导用户重连以批准新链。源码层面该逻辑由isChainsStale()实现packages/connectors/src/walletConnect.ts当isNewChainsStale为false时直接返回false否则比较config.chains中的链 ID 与命名空间eip155会话账户解析出的链 ID、以及本地存储中“已请求链”的集合是否一致存在缺口即视为 stale。同时isAuthorized()会在检测到 stale 会话时主动provider.disconnect()并返回false从而触发重新连接。showQrModal类型boolean | undefined默认值true说明是否在调用connector.connect()时展示官方的 WalletConnect 二维码弹窗。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, showQrModal: true, // [!code focus] })该默认值同样体现在源码中EthereumProvider.init({ ...parameters, showQrModal: parameters.showQrModal ?? true })packages/connectors/src/walletConnect.ts。自绘二维码提示若想关闭官方弹窗并渲染自己的二维码可设showQrModal: false然后监听message事件其 payload 为{ type: display_uri; data: string }。其背后的实现是onDisplayUri(uri)回调——连接器收到 provider 的display_uri事件后通过config.emitter.emit(message, { type: display_uri, data: uri })对外广播packages/connectors/src/walletConnect.ts。qrModalOptions类型QrModalOptions | undefined说明官方二维码弹窗的渲染选项如主题、语言等仅在showQrModal为true时生效。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, qrModalOptions: { // [!code focus] themeMode: dark, // [!code focus] }, // [!code focus] })relayUrl类型string | undefined默认值wss://relay.walletconnect.com说明WalletConnect 中继服务器地址默认使用官方公共中继可替换为自建中继。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, relayUrl: wss://relay.walletconnect.org, // [!code focus] })storageOptions类型KeyValueStorageOptions | undefined说明WalletConnect 内部键值存储的选项如自定义 storage 实现、过期策略等用于控制会话与密钥的持久化方式。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, storageOptions: {}, // [!code focus] })customStoragePrefix类型string | undefined说明为持久化 provider 状态会话、密钥对等指定自定义存储前缀常用于隔离不同 dapp/环境之间的 WalletConnect 会话数据。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ customStoragePrefix: wagmi, // [!code focus] projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })它属于EthereumProvider.init透传选项之一不在 wagmi 剔除列表中因此会原样交给底层 provider 处理。源码视角连接器的生命周期与事件流provider 的惰性初始化getProvider()packages/connectors/src/walletConnect.ts采用“单例 按需动态导入”策略首次调用时通过import(walletconnect/ethereum-provider)动态加载依赖调用EthereumProvider.init()注入projectId、optionalChains由config.chains推导、rpcMap通过extractRpcUrls从每个链的 transports 提取 RPC URL、disableProviderPing: true以及showQrModal默认值将实例缓存到provider_后续调用直接复用并把事件监听上限设为Number.POSITIVE_INFINITY。动态导入配合/* turbopackOptional: true */注释让打包器把该依赖视为可选模块——这正是它被声明为可选 peer dependency 的原因。连接流程connectconnect()packages/connectors/src/walletConnect.ts的核心步骤确定目标链优先使用传入的chainId否则读取存储中的state.chainId若属于已配置链则沿用否则回退到config.chains[0]没有任何已配置链时抛出No chains found on connector.。检查isChainsStale()若已有会话且链已 stale先provider.disconnect()断开旧会话。无会话或链 stale 时以目标链 其余链为optionalChains发起provider.connect()并将全部已配置链 ID 写入requestedChains存储。provider.enable()获取账户经getAddress规范化可选返回{ address, capabilities: {} }形态。若指定了chainId且与当前链不一致调用switchChain()切换。挂载accountsChanged、chainChanged、disconnect、session_delete监听并清理一次性使用的display_uri、connect监听。用户拒绝user rejected或连接重置connection request reset会统一转换为UserRejectedRequestError。链切换switchChainswitchChain()packages/connectors/src/walletConnect.ts优先调用wallet_switchEthereumChain请求并与config.emitter的change事件形成 Promise 竞态以确认链切换完成。若钱包返回“链未添加”类错误则回退调用wallet_addEthereumChain从config.chains或addEthereumChainParameter中提取blockExplorerUrls、rpcUrls、chainName、nativeCurrency等字段构造AddEthereumChainParameter提交用户拒绝时同样抛UserRejectedRequestError。链未配置时抛SwitchChainError内部携带ChainNotConfiguredError。事件转发连接器将 provider 事件转发为 wagmi 标准事件packages/connectors/src/walletConnect.tsaccountsChanged账户为空时视为断连否则 emitchangechainChangedemitchangechainId数字形式connectemitconnectdisconnect/session_delete清空requestedChains并 emitdisconnectdisplay_uriemitmessage自绘二维码场景使用。会话链状态持久化requestedChainsStorageKey固定为walletConnect.requestedChains${this.id}.requestedChainsgetRequestedChainsIds/setRequestedChainsIds通过config.storage读写该键packages/connectors/src/walletConnect.ts。这套状态正是isChainsStale()判定链是否失效的依据也是isNewChainsStale参数发挥作用的落点。测试验证packages/connectors/src/walletConnect.test.ts 使用msw拦截https://relay.walletconnect.com的请求并 stub 全局matchMediaWalletConnect 弹窗依赖验证了walletConnect({ projectId })能成功 setup且连接器name WalletConnectconnect参数类型包含可选的pairingTopicstring | undefined。结合 packages/connectors/package.json 中walletconnect/ethereum-provider: ^2.21.1的 peer 版本约束可确认当前仓库的兼容基线。若你的项目通过wagmi/vue/connectors导入后提示缺少该依赖请按上文安装命令补齐。小结walletConnect连接器是wagmi/vue生态中最常用的多钱包桥接方案只需一个projectId即可接入配合metadata、showQrModal、qrModalOptions、relayUrl、storageOptions、customStoragePrefix等参数完成定制而isNewChainsStale则精细控制 WalletConnect v2 “预批准链”模型下的会话失效行为。理解其底层的惰性初始化、stale 判定与事件转发机制能帮助你在多链 dapp 中做出正确的连接与异常处理决策。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 20:26:20 · 阅读 1.2k wagmi Vue 中的 WalletConnect 连接器：配置参数与底层实现深度解析
wagmi Vue 中的 WalletConnect 连接器配置参数与底层实现深度解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本指南以 site/vue/api/connectors/walletConnect.md 及其共享文档主体为核心讲解在wagmi/vue中接入 WalletConnect 连接器的完整方案。你将掌握walletConnect()的安装与导入方式、全部可配置参数projectId、metadata、isNewChainsStale、showQrModal等的语义与默认值并通过 packages/connectors/src/walletConnect.ts 的源码解读理解其连接、断连、切换链与链失效stale chain判定的底层机制。walletConnect 连接器概览walletConnect是 wagmi 为 WalletConnect 协议提供的官方连接器底层基于walletconnect/ethereum-provider实现。它是wagmi/connectors包导出的连接器之一并且被wagmi/vue/connectors入口完整转发连接器实现与类型定义位于 packages/connectors/src/walletConnect.ts包级导出声明位于 packages/connectors/src/exports/index.tsVue 框架入口通过 packages/vue/src/exports/connectors.ts 的export * from wagmi/connectors对外暴露从源码结构看walletConnect是一个工厂函数调用后返回一个符合Connector契约的createConnector配置对象其id固定为walletConnectname为WalletConnecttype为walletConnect。在 packages/connectors/src/walletConnect.test.ts 的测试中setup用例会验证connector.name WalletConnect并断言connect参数包含可选的pairingTopic字段。安装与导入安装依赖walletconnect/ethereum-provider是walletConnect连接器必需的第三方依赖。在 packages/connectors/package.json 中它被声明为可选 peer dependencywalletconnect/ethereum-provider: ^2.21.1因此需要你显式安装# pnpm pnpm add walletconnect/ethereum-provider^2.21.1 # npm npm install walletconnect/ethereum-provider^2.21.1 # yarn yarn add walletconnect/ethereum-provider^2.21.1 # bun bun add walletconnect/ethereum-provider^2.21.1需要说明的是该依赖是可选的wagmi 在getProvider()内部通过动态import(walletconnect/ethereum-provider)按需加载见下文源码解析未安装时仅在使用该连接器时才会失败。导入连接器在 Vue 项目中统一从wagmi/vue/connectors入口导入import { walletConnect } from wagmi/vue/connectors基本用法在createConfig的connectors数组中传入walletConnect()其中projectId是唯一必填参数import { createConfig, http } from wagmi/vue import { mainnet, sepolia } from wagmi/vue/chains import { walletConnect } from wagmi/vue/connectors export const config createConfig({ chains: [mainnet, sepolia], connectors: [ walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, }), ], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })随后通过useConnect()、useDisconnect()等组合式函数即可驱动连接流程。需要注意的是walletConnect()接收的类型为WalletConnectParameters源码中定义如下见 packages/connectors/src/walletConnect.ts显式声明了 wagmi 自管的字段isNewChainsStale从EthereumProviderOptions中剔除 wagmi 内部接管的部分chains、events、optionalChains、optionalEvents、optionalMethods、methods、rpcMap、showQrModalshowQrModal又被重新以可选形式开放见下文其余所有EthereumProvider.init选项原样透传。这意味着除了本文列举的参数walletconnect/ethereum-provider支持的其他初始化选项如storageOptions、relayUrl等同样可以直接传入。参数详解projectId必填类型string说明WalletConnect Cloud 项目标识符在 WalletConnect 控制台创建项目后获取。这是建立 WalletConnect v2 会话的必要凭据缺少它连接器无法初始化 provider。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, // [!code focus] })metadata类型CoreTypes.Metadata | undefined说明向钱包端展示的 dapp 元信息应用名、描述、URL、图标等会出现在钱包的授权确认界面。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, metadata: { // [!code focus] name: Example, // [!code focus] description: Example website, // [!code focus] url: https://example.com, // [!code focus] }, // [!code focus] })isNewChainsStale类型boolean | undefined默认值true说明控制“新加入配置的链”是否被判定为 stale失效。所谓 stale 链指 WalletConnect 会话中尚未与用户建立关系未批准/未拒绝的链。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ isNewChainsStale: true, // [!code focus] projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })这一参数需要结合 WalletConnect v2 的机制理解v1 支持动态切换任意链而 v2 要求用户在会话建立时预先批准一组链。具体行为如下true默认新链视为 stale。若用户在该链上尚未批准/拒绝连接器会在 dapp 自动重连时主动断开会话用户必须重新连接重新校验链才能批准新链。这是默认行为目的是避免切换链时抛出难以理解的错误例如用户根本不知道需要重新连接除非 dapp 自行处理这类错误。false新链视为潜在有效链。即使会话中尚未建立关系wagmi 也能成功自动重连代价是当钱包不支持动态会话更新时切换到未批准链会抛错。适合“dapp 频繁修改链配置、且不希望自动重连时踢掉用户”的场景此时 dapp 必须自行捕获切换错误并引导用户重连以批准新链。源码层面该逻辑由isChainsStale()实现packages/connectors/src/walletConnect.ts当isNewChainsStale为false时直接返回false否则比较config.chains中的链 ID 与命名空间eip155会话账户解析出的链 ID、以及本地存储中“已请求链”的集合是否一致存在缺口即视为 stale。同时isAuthorized()会在检测到 stale 会话时主动provider.disconnect()并返回false从而触发重新连接。showQrModal类型boolean | undefined默认值true说明是否在调用connector.connect()时展示官方的 WalletConnect 二维码弹窗。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, showQrModal: true, // [!code focus] })该默认值同样体现在源码中EthereumProvider.init({ ...parameters, showQrModal: parameters.showQrModal ?? true })packages/connectors/src/walletConnect.ts。自绘二维码提示若想关闭官方弹窗并渲染自己的二维码可设showQrModal: false然后监听message事件其 payload 为{ type: display_uri; data: string }。其背后的实现是onDisplayUri(uri)回调——连接器收到 provider 的display_uri事件后通过config.emitter.emit(message, { type: display_uri, data: uri })对外广播packages/connectors/src/walletConnect.ts。qrModalOptions类型QrModalOptions | undefined说明官方二维码弹窗的渲染选项如主题、语言等仅在showQrModal为true时生效。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, qrModalOptions: { // [!code focus] themeMode: dark, // [!code focus] }, // [!code focus] })relayUrl类型string | undefined默认值wss://relay.walletconnect.com说明WalletConnect 中继服务器地址默认使用官方公共中继可替换为自建中继。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, relayUrl: wss://relay.walletconnect.org, // [!code focus] })storageOptions类型KeyValueStorageOptions | undefined说明WalletConnect 内部键值存储的选项如自定义 storage 实现、过期策略等用于控制会话与密钥的持久化方式。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, storageOptions: {}, // [!code focus] })customStoragePrefix类型string | undefined说明为持久化 provider 状态会话、密钥对等指定自定义存储前缀常用于隔离不同 dapp/环境之间的 WalletConnect 会话数据。import { walletConnect } from wagmi/vue/connectors const connector walletConnect({ customStoragePrefix: wagmi, // [!code focus] projectId: 3fcc6bba6f1de962d911bb5b5c3dba68, })它属于EthereumProvider.init透传选项之一不在 wagmi 剔除列表中因此会原样交给底层 provider 处理。源码视角连接器的生命周期与事件流provider 的惰性初始化getProvider()packages/connectors/src/walletConnect.ts采用“单例 按需动态导入”策略首次调用时通过import(walletconnect/ethereum-provider)动态加载依赖调用EthereumProvider.init()注入projectId、optionalChains由config.chains推导、rpcMap通过extractRpcUrls从每个链的 transports 提取 RPC URL、disableProviderPing: true以及showQrModal默认值将实例缓存到provider_后续调用直接复用并把事件监听上限设为Number.POSITIVE_INFINITY。动态导入配合/* turbopackOptional: true */注释让打包器把该依赖视为可选模块——这正是它被声明为可选 peer dependency 的原因。连接流程connectconnect()packages/connectors/src/walletConnect.ts的核心步骤确定目标链优先使用传入的chainId否则读取存储中的state.chainId若属于已配置链则沿用否则回退到config.chains[0]没有任何已配置链时抛出No chains found on connector.。检查isChainsStale()若已有会话且链已 stale先provider.disconnect()断开旧会话。无会话或链 stale 时以目标链 其余链为optionalChains发起provider.connect()并将全部已配置链 ID 写入requestedChains存储。provider.enable()获取账户经getAddress规范化可选返回{ address, capabilities: {} }形态。若指定了chainId且与当前链不一致调用switchChain()切换。挂载accountsChanged、chainChanged、disconnect、session_delete监听并清理一次性使用的display_uri、connect监听。用户拒绝user rejected或连接重置connection request reset会统一转换为UserRejectedRequestError。链切换switchChainswitchChain()packages/connectors/src/walletConnect.ts优先调用wallet_switchEthereumChain请求并与config.emitter的change事件形成 Promise 竞态以确认链切换完成。若钱包返回“链未添加”类错误则回退调用wallet_addEthereumChain从config.chains或addEthereumChainParameter中提取blockExplorerUrls、rpcUrls、chainName、nativeCurrency等字段构造AddEthereumChainParameter提交用户拒绝时同样抛UserRejectedRequestError。链未配置时抛SwitchChainError内部携带ChainNotConfiguredError。事件转发连接器将 provider 事件转发为 wagmi 标准事件packages/connectors/src/walletConnect.tsaccountsChanged账户为空时视为断连否则 emitchangechainChangedemitchangechainId数字形式connectemitconnectdisconnect/session_delete清空requestedChains并 emitdisconnectdisplay_uriemitmessage自绘二维码场景使用。会话链状态持久化requestedChainsStorageKey固定为walletConnect.requestedChains${this.id}.requestedChainsgetRequestedChainsIds/setRequestedChainsIds通过config.storage读写该键packages/connectors/src/walletConnect.ts。这套状态正是isChainsStale()判定链是否失效的依据也是isNewChainsStale参数发挥作用的落点。测试验证packages/connectors/src/walletConnect.test.ts 使用msw拦截https://relay.walletconnect.com的请求并 stub 全局matchMediaWalletConnect 弹窗依赖验证了walletConnect({ projectId })能成功 setup且连接器name WalletConnectconnect参数类型包含可选的pairingTopicstring | undefined。结合 packages/connectors/package.json 中walletconnect/ethereum-provider: ^2.21.1的 peer 版本约束可确认当前仓库的兼容基线。若你的项目通过wagmi/vue/connectors导入后提示缺少该依赖请按上文安装命令补齐。小结walletConnect连接器是wagmi/vue生态中最常用的多钱包桥接方案只需一个projectId即可接入配合metadata、showQrModal、qrModalOptions、relayUrl、storageOptions、customStoragePrefix等参数完成定制而isNewChainsStale则精细控制 WalletConnect v2 “预批准链”模型下的会话失效行为。理解其底层的惰性初始化、stale 判定与事件转发机制能帮助你在多链 dapp 中做出正确的连接与异常处理决策。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考