手把手教你用 ethers.js 与 Ant Design Web3 构建 DApp

关键词：ethers.js、React、Ant Design Web3、DApp、去中心化钱包、Ethereum

想要又快又稳地把 Web3 功能集成进 React？本文以 ethers.js 为主线，结合 Ant Design Web3 组件库，拆解安装、配置、Provider/Signer 获取及常见坑位，附真实示例，帮你30 分钟内跑通第一个 DApp。

1. 极速入门：三步装好开发环境

1.1 安装核心依赖

以下命令一次性拉齐所有文件，一行搞定！

npm i @ant-design/web3 @ant-design/web3-ethers ethers --save

若使用 yarn 或 pnpm，只需把 npm i 替换为你喜欢的管理器即可。

1.2 引入 Provider，搭建全局上下文

import React from 'react';
import { EthersWeb3ConfigProvider } from '@ant-design/web3-ethers';
import { Main } from './Main';

export default function App() {
  return (
    <EthersWeb3ConfigProvider
      chains={[{ id: 1 }, { id: 5 }]} // 主网 & Goerli
      wallets={['MetaMask']}
      ens
      balance
    >
      <Main />
    </EthersWeb3ConfigProvider>
  );
}

关键词「React、ethers、Provider」的完整上下文一次性嵌入，避免未来因 Import 遗漏而反复出 bug。

2. 在业务组件里拿 Provider & Signer

import React from 'react';
import { ConnectButton } from '@ant-design/web3';
import { useEthersProvider, useEthersSigner } from '@ant-design/web3-ethers';

export default function Main() {
  const provider = useEthersProvider();
  const signer = useEthersSigner();

  return (
    <div>
      <ConnectButton />
      <p>Provider 对象：{provider ? provider.connection.url : '未连接'}</p>
      <p>Signer 地址：{signer ? '已就绪' : '请先签名'}</p>
    </div>
  );
}

一旦用户点击 ConnectButton 并授权钱包，provider 与 signer 即刻可用，无需额外监听事件。

3. ethers v5 用户如何无痛迁移？

场景	操作说明
必须使用旧版	`npm i ethers@legacy-v5 @ant-design/web3-ethers-v5 --save`
适配器换名	将 `@ant-design/web3-ethers` 换为 `@ant-design/web3-ethers-v5`
API 保持一致	开发者无需改动 React Hook 名称即可继续工作

但官方强烈建议升级到最新 ethers v6，可获得 EIP-1559、EIP-4337 的完整支持及性能优化。

4. `EthersWeb3ConfigProvider` 常见配置详解

属性	作用	实战示例
chains	指定可连接链	生产环境建议 `[{ id: 1 }, { id: 137 }]`
wallets	声明钱包类型	支持 `'MetaMask'`、`'WalletConnect'` 或自定义 WalletFactory
ens	是否解析 ENS	打开后自动把 `0x...` 变 `vitalik.eth`
balance	是否展示余额	建议打开，提升用户体验
eip6963	与多钱包插件共存的协议	桌面浏览器可同时识别 Phantom、MetaMask
walletConnect	WalletConnect V2 配置	扫码登录必备，需填 ProjectId
storage	本地 session 存储	断网/刷新不丢失钱包连接状态

5. 5 分钟生成「钱包登录 + 余额展示」页面

完整代码示例

import React from 'react';
import { EthersWeb3ConfigProvider } from '@ant-design/web3-ethers';
import { NFTCard, Address } from '@ant-design/web3';
import { Main } from './Main';

function App() {
  return (
    <EthersWeb3ConfigProvider
      chains={[{ id: 137 }]}
      wallets={['MetaMask']}
      walletConnect={{ projectId: '你的ProjectId' }}
      balance
    >
      <NFTCard address="0x..." tokenId={99} />
      <Main />
    </EthersWeb3ConfigProvider>
  );
}

👀 仅用不到 50 行代码，你就拿到了钱包登录按钮、ENS 地址、NFT 预览、余额实时刷新的一站式体验。

6. 实战坑位避坑指南

浏览器扩展阻挡
用户安装多个钱包插件时，优先使用 EIP-6963。否则 window.ethereum 会被最后安装的覆盖。
链 ID 元数据缺失
生产环境请补充 rpcUrls 与 nativeCurrency，否则 Ant Design Web3 无法默认识别名称与符号。
链上不支持的 ENS
ENS 目前只在主网 & Goerli 可用，其他链即使配置 ens={true} 也会静默降级为普通地址展示。

7. 常见问题答疑（FAQ）

Q1：组件库能对接硬件钱包吗？
A：可以。硬件钱包通常通过 WalletConnect 或自定义 WalletFactory 接入，只要在 wallets 里声明即可。

Q2：为什么 signer 返回 undefined？
A：你必须先点 ConnectButton 进行用户授权，此后 React Context 才会注入有效 signer。

Q3：如何对一次交易二次确认再签名？
A：拿到 signer 后，正常触发 await signer.sendTransaction(tx)。Ant Design Web3 已封装 UI，用户可直接在弹窗里再次核对。

Q4：生产需要 https 环境吗？
A：WalletConnect 与大多数移动端钱包强制 https；本地测试可用 npm run dev -- --host --https 快速生成自签名证书。

Q5：怎么监听网络切换？
A：EthersWeb3ConfigProvider 内部已自动监听 chainChanged 与 accountsChanged，状态会通过 React Context 回传，你只需订阅 React state 即可，无需手写 EventBus。

Q6：需要写 TypeScript 吗？
A：组件库自带完整声明文件，JavaScript 也无压力，但强推 TypeScript，可减少隐式错误，尤其在链 ID 与 BigNumber 运算场景。

8. 扩展阅读与下一步

想继续深挖这些主题？

👉 点击了解 WalletConnect V2 最佳实践及调试技巧

此外，你还可以把本文仓库改造成 React + ethers.js 的 CLI 模板，一行 npx create-my-dapp 即可开箱即用。

👇 随手收藏实战资源的另一条通道

👉 零门槛 DApp 脚手架：一键部署到测试网

掌握了以上要点，你就能在下一个项目中轻松嵌入 React、Web3 组件 的流畅体验，同时满足 SEO 优化「以太坊开发教程」、「React DApp」 的一切关键词需求。祝编码愉快！