完整指南：使用 JavaScript 将 WalletConnect 集成到 DApp，实现一键加密钱包登录

在 Web3 浪潮中，DApp（去中心化应用）需要让用户无需交出私钥即可签署交易。WalletConnect 正是一种为 DApp 与加密钱包之间建立端到端加密通道的开放协议。本文将手把手教你从零开始把 WalletConnect 织入 JavaScript 前端，带来丝滑又安全的钱包登录体验。

1. WalletConnect 是什么？

WalletConnect 以 二维码握手 为核心：用户用手机钱包扫码即可授权，整个流程

• 私钥始终保存在用户设备；
• 传输全程 E2E 加密；
• 支持 MetaMask、Trust Wallet、Ledger Live 等主流钱包。

对前端开发者来说，它是一套标准化接口，不必再为每个钱包做单独适配。

2. 为何在 DApp 中加入 WalletConnect？

• 安全升级：私钥永不离开本地。
• 体验升级：扫一扫即可使用；无需浏览器插件的用户也能玩 Web 端页面。
• 钱包兼容：一次集成，连接数百万钱包用户。
• 维护简化：官方协议长期更新，社区活跃。

3. 准备工作与依赖安装

在空目录下初始化 Node 项目，再装以下包：

• @walletconnect/web3-provider：官方 Provider 实现；
• qrcode-terminal（开发调试时可选）：终端即时展示二维码。

npm install @walletconnect/web3-provider qrcode-terminal

或

yarn add @walletconnect/web3-provider qrcode-terminal

👉 跟着这份 5 分钟速查表，跳过凹坑直接部署。

4. 在 JavaScript 中引入 Provider 并初始化

ES 模块写法：

import WalletConnectProvider from "@walletconnect/web3-provider";
// 若调试 Node 终端可引入
import QRCodeTerminal from "qrcode-terminal";

创建实例时通常需要：

• bridge：中继服务器的 WS 地址（默认云端即可）；
• qrcodeModalOptions：决定移动端 Deeplink 顺序。

const provider = new WalletConnectProvider({
  bridge: "https://bridge.walletconnect.org",
  qrcodeModalOptions: {
    // 优先 App 弹起顺序
    mobileLinks: [
      "metamask://",
      "trust://"
    ]
  }
});

5. 连接钱包

await provider.enable(); // 弹出二维码，等待用户扫码授权

连接成功后会得到账户数组：

const accounts = provider.accounts; // ["0x..."]

6. 处理 3 大关键事件

provider.on("connect", (err, payload) => {
  if (!err) {
    console.log("WalletConnect 已连接", payload.params[0].accounts);
  }
});

provider.on("session_update", (err, payload) => {
  // 账户/网络发生变更
});

provider.on("disconnect", (err, payload) => {
  // 用户主动退出
});

7. 用 Web3.js 发送交易

import Web3 from "web3";
const web3 = new Web3(provider);

// 构造交易
const tx = {
  from: accounts[0],
  to: "0x交易所地址",
  value: web3.utils.toWei("0.01", "ether"),
  gas: 21000,
  gasPrice: await web3.eth.getGasPrice()
};

const receipt = await web3.eth.sendTransaction(tx);
console.log("交易哈希", receipt.transactionHash);

8. 交易确认与错误处理

web3.eth.sendTransaction(tx)
  .on("transactionHash", h => console.log("广播成功：", h))
  .on("confirmation", (c, r) => console.log(`第 ${c} 次确认`))
  .on("error", e => console.error("失败：", e));

9. 断开连接

provider.disconnect();

触发 disconnect 事件后，可在页面清除用户缓存并跳回首页。

FAQ | 高频问答

Q1：测试网上也能用 WalletConnect 吗？
A：完全可行，只需要将 DApp 默认网络切换为 chainId=5（Goerli）等测试网即可。

Q2：桌面浏览器没有扫码功能怎么办？
A：@walletconnect/web3-provider 会自动弹出网页“QR Code Modal”[桌面浏览器截屏扫码]；若想提升体验，可接入 @walletconnect/modal 自定义 UI。

Q3：是否必须与 MetaMask 兼容？
A：WalletConnect 原生已经兼容 150+ 款钱包，无需额外代码。

Q4：如何防止反复弹出 QR 码？
A：把 session 储存在本地 localStorage，下次页面刷新时通过 provider = await new WalletConnectProvider({ ... }).enable() 即可自动续命，仅断网或超时才会再次扫码。

Q5：代码体积会不会过大？
A：Webpack tree-shaking 后约 100-150 KB（gzip），相比直接导入整套 SDK 减少 50% 以上。

👉 三分钟格式连招，把包体降到 80 KB 以内！。

实战示例：快捷登录按钮

如果只需“登录”而不需整个 Web3 实例，最简流程如下：

document.getElementById('loginBtn').addEventListener('click', async () => {
  const p = new WalletConnectProvider({ bridge: "https://bridge.walletconnect.org" });
  try {
    await p.enable();
    alert("已登录：" + p.accounts[0]);
  } catch (e) {
    alert("用户拒绝：" + e.message);
  }
});

小结

WalletConnect 不仅提升了 DApp 的安全性，也兼顾了轻量级用户的体验。按上文顺序装载依赖、监听事件、提交交易，你已拥有生产级多链钱包登录能力。祝编码愉快，早日收获 10 万活跃用户！