从零开始构建你的第一个 Web3 DApp —— 2. DApp 连接钱包

前言

在去中心化应用（DApp）中，钱包是用户与区块链交互的入口。用户的钱包地址相当于他们的“账号”，而签名交易则是他们在链上的“操作凭证”。因此，连接钱包 是 DApp 中最重要的功能之一。没有钱包连接，用户就无法进行转账、签名、参与合约调用，也就失去了 DApp 的核心价值。

本节课程将带你逐步实现 DApp 钱包连接功能。我们将使用 wagmi 和 Ant Design Web3 这两个强大且现代化的工具库，帮助你快速构建一个支持钱包交互的前端应用。

一、DApp 如何连接钱包

在以太坊生态中，常见的钱包连接方式主要有三种：

1. 浏览器插件钱包

   • 最常见的方式，如 MetaMask。钱包通过浏览器扩展注入全局对象 window.ethereum，DApp 可直接调用接口与钱包交互。

2. 钱包 App 内置浏览器

   • 用户在钱包 App 内访问 DApp 页面（如 TokenPocket、imToken）。DApp 通过钱包内置的 WebView 提供的接口进行交互。

3. WalletConnect 协议

   • 通过扫描二维码或深度链接建立连接，钱包和 DApp 之间通过中继服务转发消息，适合跨设备使用。

前两种方式依赖“钱包注入接口”，而钱包注入主要遵循两种协议：

• EIP-1193：早期标准，接口较为简单，目前应用广泛。
• EIP-6963：更新协议，正在逐步推广，提供更丰富的多钱包支持能力。

在本教程中，我们将以 EIP-1193 为例，先实现与钱包的连接。

二、准备工作

1. 安装 MetaMask 钱包

• 访问 MetaMask 官网，下载并安装浏览器插件。
• 安装后，按照提示完成初始设置（创建钱包或导入助记词）。
• 安装完成后，你会在浏览器右上角看到小狐狸图标，这就是 MetaMask 钱包入口。

2. 准备开发环境

在项目目录下安装所需依赖：

npm install wagmi @ant-design/web3 @ant-design/web3-wagmi

wagmi：React Hooks 封装的 Web3 工具库。

@ant-design/web3：Ant Design Web3 UI 组件库。

@ant-design/web3-wagmi：提供 wagmi 与 Ant Design Web3 的集成支持。

三、代码实现

下面我们一步一步实现钱包连接功能。

1. 基础配置

在 React 项目中创建一个组件 Web3.tsx：

import { http } from "wagmi";
import { Mainnet, WagmiWeb3ConfigProvider, MetaMask } from '@ant-design/web3-wagmi';
import { Address, NFTCard, Connector, ConnectButton } from "@ant-design/web3";

export default function Web3() {
  return (
    <WagmiWeb3ConfigProvider
      chains={[Mainnet]}
      transports={{
        [Mainnet.id]: http(),
      }}
      wallets={[MetaMask()]}
    >
      <Address format address="0xEcd0D12E21805803f70de03B72B1C162dB0898d9" />
      <NFTCard
        address="0xEcd0D12E21805803f70de03B72B1C162dB0898d9"
        tokenId={641}
      />
      <Connector>
        <ConnectButton />
      </Connector>
    </WagmiWeb3ConfigProvider>
  );
};

2. 关键组件说明

• MetaMask()：代表小狐狸钱包。Ant Design Web3 支持多款钱包（如 TokenPocket、imToken、WalletConnect 等），你可以根据需要在 wallets 数组中自由添加。MetaMask() 会自动帮你与 wagmi 配置对接，简化集成步骤。
• Connector：连接器组件，提供上下文和逻辑管理，负责处理连接、断开、状态监听等一系列交互逻辑。它不仅仅是 UI 容器，更是钱包交互的核心“控制器”。
• ConnectButton：配合 Connector 使用的按钮，点击后会调用钱包连接逻辑。如果已连接，它会自动显示用户状态（如钱包地址缩写），如果未连接则显示“Connect Wallet”。
• Address：展示指定地址的组件，可以将链上地址以多种格式显示（完整地址、缩写、中间省略等），提高用户体验。
• NFTCard：一个展示 NFT 资产的 UI 组件，传入合约地址和 tokenId 后，它会自动获取链上数据并渲染出卡片式展示，非常适合快速搭建展示页面。

3. 效果展示

• 初始页面：显示“Connect Wallet”按钮。
• 点击后：弹出 MetaMask 窗口，用户确认连接。
• 连接成功：页面展示用户地址和相关信息。

四、运行效果

1. 连接前\ 页面显示“Connect Wallet”按钮，等待用户交互。
2. 连接中\ 弹出 MetaMask 窗口，提示用户授权。
3. 连接后

• 页面显示钱包地址。
• 可以进一步展示用户的资产，如 NFT、代币余额等。

五、扩展与进阶

1. 支持多个钱包

Ant Design Web3 内置了多种钱包支持，如 TokenPocket、imToken 等。只需在 wallets 配置中添加即可：

wallets={[MetaMask(), TokenPocket(), ImToken()]}

2. 使用 WalletConnect

如果需要支持手机钱包，可以引入 WalletConnect：

import { WalletConnect } from '@ant-design/web3-wagmi';

wallets={[MetaMask(), WalletConnect()]}

3. 常见错误处理

• 用户拒绝连接：监听异常，提示“连接被拒绝”。
• 网络不匹配：检查链 ID，提示用户切换到正确网络。
• 连接丢失：监听 disconnect 事件，自动重试或提示用户重新连接。

六、总结

在本节中，我们学习了如何在 DApp 中实现钱包连接功能：

1. 了解了钱包连接的三种方式及相关协议（EIP-1193 / EIP-6963）。
2. 安装配置了 MetaMask，并搭建了基础开发环境。
3. 使用 wagmi 与 Ant Design Web3 快速实现了钱包连接功能。
4. 学习了如何扩展支持多钱包、WalletConnect，以及如何处理常见错误。

连接钱包是 DApp 的第一步。有了它，我们才能进一步实现 链上交互，比如代币转账、合约调用、消息签名等。在下一节，我们将继续探索 如何与智能合约进行交互，让 DApp 真正具备业务功能。