基于WalletConnect的深度链接对接移动钱包问题咨询

核心原因 #

该问题90%以上的场景是因为metamask://深度链接后拼接的WalletConnect URI没有做二次URL编码，导致MetaMask无法解析到完整的会话参数，仅唤起应用不触发授权流程。

可落地修复步骤 #

• 修复URI编码逻辑
  拼接深度链接时，需要将完整的WalletConnect URI整体做一次URL编码后，再拼到metamask://wc?uri=参数后，不能直接拼接未二次编码的串。
  示例逻辑（JS环境）：

  const wcUri = "wc:87dc2f44-42ff-4206-81bf-f2685730759d@1?bridge=https%3A%2F%2Fp.bridge.walletconnect.org&key=bbd16a77194580dc2c4b8caf02fd5d269bf9c0efdb7fbf91673bc3a7eadf0c25"
  // 核心操作：对完整wcUri做二次编码
  const encodedWcUri = encodeURIComponent(wcUri)
  const deepLink = `metamask://wc?uri=${encodedWcUri}`
  

  编码后wc串中的?、&会被转义为%3F、%26，MetaMask就能正确解析完整的会话参数。

• 调整会话初始化时序
  必须先完成WalletConnect客户端的会话初始化、监听回调注册，再触发深度链接唤起钱包。如果先唤起钱包再初始化本地监听，钱包的授权请求无法被你的应用捕获，也会出现无确认弹窗的问题。

• 协议与版本兼容检查

  1. WalletConnect V1协议已经正式停止服务，建议直接升级到V2版本协议，V2对移动端深度链接的适配逻辑更完善，不会出现V1的偶发解析失败问题
  2. 检查MetaMask移动端版本，低于V2.15.0的旧版本对深度链接的支持存在已知bug，升级到最新版本即可验证

• 多钱包兼容适配
  如果需要对接TrustWallet等其他钱包，不要硬编码钱包Scheme，不同钱包的唤起前缀不同：

  • TrustWallet对应前缀为trust://wc?uri=
  • 所有钱包的拼接逻辑都需要遵守「wc URI二次编码」的规则

验证方式 #

你可以先打印拼接完成的完整深度链接，提取uri参数的值做URL解码，确认解码结果和你生成的原始WalletConnect URI完全一致，没有参数被截断的情况，即可确认编码逻辑没问题。

内容的提问来源于stack exchange，提问作者0x797979