常见问题、坑点与最佳实践

📚 作者：Henry 🧱 系列：《区块链钱包原理与前端集成实践》 · 第 6 篇 👨‍💻 受众：Web3 开发者 / 区块链学习者\ 👉 系列持续更新中，建议收藏专栏或关注作者

实际开发过程中，我们总是会遇到各种各样的问题，遇到问题不可怕，可怕的是自己心慌。这儿先给大家列举若干高频、易忽略的常规问题，先做个积累，让自己在遇到问题时先有自查的方向和思路。

连接器 / wagmi 配置类问题

1. useAccount 报错：未包裹 WagmiProvider

   • 💥 表现：页面闪退 / Hook 报错
   • ✅ 解决：确保 React 组件树由 <WagmiProvider> 包裹，且传入 config 实例

   // 正确用法：
   <WagmiProvider config={config}>
     <App />
   </WagmiProvider>
   
   // 否则，会报错：
   // Cannot call useAccount() outside of WagmiProvider

2. AutoConnect 无效：刷新后状态丢失

   • 💥 表现：刷新页面需重新连接
   • ✅ 原因：未使用持久化存储或上次连接器信息未保存

   // 第一步：在wagmi config 中开启自动连接
   export const config = createConfig({
     autoConnect: true, // ✅ 启用自动连接
     connectors: [...],
     publicClient,
   })
   // 第二步：配合localstorage存储连接器信息
   localStorage.setItem('last-connector', connector.id)

3. WalletConnect QR 二维码加载失败

   • 💥 表现：未弹出二维码窗口
   • ✅ 解决：检查是否传入 projectId，showQrModal 设置为 true，检查网络代理阻拦

   walletConnect({
     projectId: 'YOUR_PROJECT_ID', // 必填
     showQrModal: true,            // 必须为 true 否则不会弹窗
   })

4. 多个连接器优先级冲突

   • 💥 表现：Injected Wallet 总是覆盖 WalletConnect
   • ✅ 解决：在 UI 层暴露连接器选择器，或记录上次连接器 (localStorage.setItem('lastConnector'))

   // 在UI层暴露控制连接器
   const walletConnectConnector = connectors.find(c => c.id === 'walletConnect')
   connect({ connector: walletConnectConnector }) // 显式指定

5. 无法识别当前连接器名称

   • 💥 表现：UI 显示“Unknown wallet”
   • ✅ 使用 useAccount().connector?.name 替代硬编码检测

   const { connector } = useAccount()
   console.log(connector?.name) // 如 "MetaMask"、"WalletConnect"

🧩 链 ID / 网络环境问题

1. 链不匹配，导致 provider 调用失败
   • 💥 报错：Unsupported chain ID
   • ✅ 使用 useNetwork().chain.unsupported 判断，并使用 useSwitchChain 自动切换
2. 部分钱包不支持自动切链（如 Rainbow）
   • 💥 表现：wallet_switchEthereumChain 无反应
   • ✅ 提供链 ID + 手动操作提示：显示 chainId 与链名
3. 钱包连接成功但地址为 null
   • 💥 原因：WalletConnect 未同步返回账户信息
   • ✅ 监听 onConnect 与 accountsChanged，或延迟渲染业务组件直到 address 可用
4. 连接钱包后网络变更未触发更新
   • 💥 原因：未监听 chainChanged 事件
   • ✅ 使用 wagmi 自动更新链状态；如自定义 provider，需手动注册监听器

🧩 签名与合约钱包兼容问题

1. 合约钱包签名失败（Safe / Argent）
   • 💥 报错：方法不支持 / 返回空签名
   • ✅ 使用 EIP-1271 验证合约签名
2. EIP-712 签名在移动钱包中失败
   • 💥 报错：无响应或内容被修改
   • ✅ 检查 domain 中 chainId、name 与类型结构一致性，推荐使用 siwe 工具包处理复杂结构
3. 签名返回地址不一致
   • 💥 表现：验证失败，登录不生效
   • ✅ 解决：确认签名地址与 signer.getAddress() 一致，避免多账户状态混乱
4. 用户拒绝签名 / 连接无提示
   • 💥 表现：UI 无响应
   • ✅ 使用 try-catch 包裹签名过程，提示“签名已取消 / 连接被拒绝”

🧩 WalletConnect / Session 管理问题

1. WalletConnect 会话未持久化
   • 💥 表现：刷新后连接断开，但 UI 显示已连接
   • ✅ 强制 session 检查：通过 connector?.storage?.getItem() 验证
2. WalletConnect 重连触发重复连接请求
   • 💥 原因：未正确处理 wagmi autoConnect 与 QR 会话共存逻辑
   • ✅ 方案：记录 lastConnector，页面刷新时仅尝试 reconnect（不重复触发 connect）
3. WalletConnect 无法发送交易
   • 💥 报错：eth_sendTransaction 拒绝
   • ✅ 排查是否缺少 gasLimit / from 字段，或是否连接的是只读 provider
4. 不同钱包返回签名结构不一致
   • 💥 表现：同一签名结构，Wallet A 成功，Wallet B 验证失败
   • ✅ 使用 Ethers.js 的 verifyMessage / TypedDataEncoder 统一格式化验证

🧩 UI 交互与用户体验问题

1. 签名过程中用户误点其他按钮

   • 💥 表现：用户重复点击导致多次签名请求
   • ✅ 禁用签名按钮 + 显示 SignaturePrompt

2. 连接中状态丢失（例如点击按钮后无动画）

   • 💥 原因：未设置连接状态 loading 标志
   • ✅ useConnect().isLoading 用于控制按钮状态

3. 钱包未安装导致页面白屏 / 卡顿

   • 💥 原因：直接使用 window.ethereum 报错
   • ✅ 判断是否存在注入对象：if (!window.ethereum) { showInstallPrompt() }

4. 未处理 accountsChanged 事件

   • 💥 用户切换钱包后，仍显示旧地址

   • ✅ wagmi 自动处理该事件，手动 provider 需监听：

     window.ethereum.on('accountsChanged', handleChange)

5. 签名过期/重放攻击未处理

   • 💥 登录状态可被伪造
   • ✅ 使用 nonce + 服务端验证签名是否有效，并设定过期时间