WalletConnect 无法正常工作？常见问题和修复

连接初始化失败

1. 由于 dApp 和钱包之间的链 ID 不匹配，WalletConnect 会话无法启动。 dApp 必须在其连接请求中显式声明目标区块链网络 ID，否则钱包会拒绝握手。

2. URI 参数丢失或格式错误会妨碍移动设备上正确的深度链接。 Android 意图过滤器和 iOS 通用链接配置必须与 WalletConnect 所需的架构格式精确一致。

3. 基于浏览器的 dApp 在尝试与 WalletConnect 中继服务器建立 WebSocket 连接时遇到 CORS 限制。除非配置了正确的代理标头或中继端点，否则这会阻止握手完成。

4. 用户代理检测逻辑错误地将桌面浏览器识别为移动浏览器，从而触发不受支持的二维码流而不是直接配对。这会导致空白模式显示，没有可操作的 UI 元素。

5. 在高延迟网络条件下超过中继服务器超时阈值。默认 15 秒超时会导致在注册钱包批准之前会话过早中止。

会话持续性故障

1. 当用户离开 dApp 选项卡或关闭浏览器窗口时，会话存储会被无意清除。如果钱包在重新启动后未保留配对元数据，则基于 LocalStorage 的会话恢复将失败。

2、同源发起的多个并发会话会覆盖彼此的会话状态。这会导致签名请求不一致，钱包会签署过时的交易上下文。

3. WalletConnect v2.0 基于主题的加密密钥在应用程序重新加载时重新生成，而不保留原始密钥派生路径。随后的消息解密会默默失败。

4. 基于 Chromium 的浏览器中的后台选项卡限制会暂停 WalletConnect 事件侦听器，从而导致延迟或错过会话批准通知。

5. 移动操作系统内存管理会在会话确认完成之前终止后台钱包进程，使 dApp 处于不确定的挂起状态。

签名和交易处理错误

1. EIP-1559 交易参数在有效负载中被省略或格式错误，导致钱包退回到传统的 Gas 定价并彻底拒绝请求。

2. 交易有效负载超过 WalletConnect 中继基础设施规定的 1MB 大小限制。大型合约部署或批量操作会触发静默截断。

3. 钱包对 dApp 源头执行严格的域验证，但不会在错误消息中公开拒绝原因。尽管签名请求有效，开发人员还是会看到通用的“用户被拒绝”。

4. 多链 dApp 在链切换后无法更新活动会话命名空间。钱包继续在之前的链上签名，产生无效签名。

5. 在会话建立期间，dApp 中配置的自定义 RPC 端点不会传播到钱包。钱包使用默认端点，导致块高度不匹配和随机数错误。

钱包端兼容性差距

1. 较旧的钱包版本缺乏对 WalletConnect v2.0 对称加密模型的支持，导致握手尝试失败且无法回退到 v1.0 协议。

2. 硬件钱包集成在会话提议期间省略了所需的证明证明，违反了 WalletConnect 对安全元素支持的签名者的安全要求。

3. 实现自定义 UI 流的钱包会覆盖 WalletConnect 的标准化模式行为，打破 dApp 对一致回调计时的期望。

4. 钱包特定的十六进制字符串编码方案偏离了以太坊规范的字节数组序列化，导致地址验证期间校验和不匹配。

5. 钱包将会话持续时间限制为 7 天，而没有向 dApp 开发人员公开此策略，从而导致在长期运行的质押或治理接口期间出现意外的会话过期。

调试和诊断工具

1. WalletConnect Explorer 仪表板提供实时中继日志，但由于系统间时钟不同步，需要手动与 dApp 客户端时间戳关联。

2. SDK 调试模式仅在使用显式enableLogging: true标志进行初始化时才会发出详细控制台输出 - 默认配置会抑制所有诊断跟踪。

3. 即使在部分服务降级期间，中继运行状况端点也会返回 HTTP 200，从而掩盖间歇性消息传送失败。

4. WalletConnect CLI 工具验证 URI 结构，但不模拟实际的移动深度链接解析，缺少特定于平台的解析边缘情况。

5. 浏览器扩展注入器会干扰 WalletConnect 的 iframe 通信层，注入与本机 SDK 处理程序竞争的重复事件侦听器。

常见问题解答

问：为什么钱包扫描二维码成功后，我的 dApp 却显示“连接超时”？答：当中继服务器无法在配置的超时窗口内将批准事件从钱包转发到 dApp 时，就会发生这种情况 - 通常是由于网络拥塞或中继负载不平衡。

问：我可以在同一根域的不同子域之间重复使用 WalletConnect 会话吗？答：不需要。每个子域都被浏览器视为单独的源，需要不同的会话初始化和存储隔离。

问：当我的 dApp 使用 Content-Security-Policy 标头时，为什么 WalletConnect 会失败？答：严格的 CSP 指令会阻止 WalletConnect 基于 iframe 的通信层使用的动态脚本注入，除非允许“不安全内联”或特定的随机数值。

问：如何验证钱包是否支持 WalletConnect v2.0 的批量请求等可选功能？答：通过session.getNamespaces()查询钱包的功能，并检查方法数组是否存在eth_sendTransactionBatch 。