从零开始构建你的第一个 Web3 DApp —— 1. 用 React + Ant Design Web3 展示 NFT

本教程参考自 WTF Academy 的《WTF-Dapp》，面向有前端基础、想要迈入 Web3 的开发者。你将学会如何用 React + Next.js + Ant Design Web3 快速搭建一个 DApp，并在网页中展示链上的 NFT。

1. 前置条件

在开始前，你需要：

• 熟悉 React（若不熟悉请先学习 React 官方文档）
• 安装 Node.js ≥ 20（带 npm/npx）

检查版本：

node -v # v20.0.0+
npm -v  # 10.0.0+
npx -v  # 10.0.0+

2. 初始化 React 项目（Next.js + TS）

使用 Next.js 官方脚手架： npx create-next-app@14.0.4 选择配置时建议：

• 去掉 Tailwind CSS 和 App Router（简化项目）
• 项目命名为 ant-design-web3-demo

进入目录并安装依赖：

cd ant-design-web3-demo
npm i
npm run dev

打开 <http://localhost:3000>，看到页面说明环境已就绪 ✅。

3. 安装 Ant Design Web3 依赖

在项目中安装必要依赖：

npm i antd @ant-design/web3 @ant-design/web3-wagmi wagmi @tanstack/react-query --save

• @ant-design/web3：Ant Design 的 Web3 组件库

• @ant-design/web3-wagmi：适配器，基于 wagmi 2.x，让组件直接连以太坊

• wagmi：开源 React Hooks Web3 工具库

• @tanstack/react-query：数据请求管理（wagmi 依赖） 修复 Next.js 配置（next.config.js）：

const nextConfig = {
  reactStrictMode: true,
+ transpilePackages: [ "@ant-design", "antd", "rc-util", "rc-pagination", "rc-picker", "rc-input" ],
}

4. 添加第一个 Web3 组件

新建 pages/web3.tsx 文件：

import { Address } from "@ant-design/web3";

export default function Web3() {
  return (
    <Address format address="0xEcd0D12E21805803f70de03B72B1C162dB0898d9" />
  );
}

访问 <http://localhost:3000/web3>，你会看到地址已经渲染成功 🎉。

小优化：在 styles/global.css 添加

html, body {
  min-height: 100vh;
}

5. 配置 wagmi 适配器

Ant Design Web3官方地址 Ant Design Web3 官方提供了 wagmi、ethers 等多个框架的适配器来适配以太坊，我们推荐使用 @ant-design/web3-wagmi，它是一个基于 wagmi 2.x 的 Ant Design Web3 以太坊适配器。它为 @ant-design/web3 的组件提供了连接以太坊等 EVM 兼容链的能力。通过它，你不需要自己处理组件的连接状态，链数据请求等逻辑。它会通过 Web3ConfigProvider 为组件提供相关全局状态和接口。

从官方介绍可以看出，wagmi库的使用需要熟练掌握。我们来看一个实例

import { ConnectButton, Connector } from '@ant-design/web3';
import {
  Mainnet,
  MetaMask,
  OkxWallet,
  TokenPocket,
  WagmiWeb3ConfigProvider,
  WalletConnect,
} from '@ant-design/web3-wagmi';
import { QueryClient } from '@tanstack/react-query';
import { http } from 'wagmi';

const queryClient = new QueryClient();

const App: React.FC = () => {
  return (
    <WagmiWeb3ConfigProvider
      eip6963={{
        autoAddInjectedWallets: true,
      }}
      ens
      chains={[Mainnet]}
      transports={{
        [Mainnet.id]: http(),
      }}
      walletConnect={{
        projectId: YOUR_WALLET_CONNECT_PROJECT_ID,
      }}
      wallets={[
        MetaMask(),
        WalletConnect(),
        TokenPocket({
          group: 'Popular',
        }),
        OkxWallet(),
      ]}
      queryClient={queryClient}
    >
      <Connector
        modalProps={{
          mode: 'simple',
        }}
      >
        <ConnectButton quickConnect />
      </Connector>
    </WagmiWeb3ConfigProvider>
  );
};

export default App;

这段代码是一个使用 React + Wagmi + Ant Design Web3 的示例组件（App），用于在 Web 应用中集成多种以太坊/区块链钱包（如 MetaMask、WalletConnect、TokenPocket、OKX Wallet），并提供一个 UI 按钮用于连接钱包。它通过 WagmiWeb3ConfigProvider 为应用提供全局的 Web3 

修改 web3.tsx，引入 wagmi：

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

export default function Web3() {
  return (
    <WagmiWeb3ConfigProvider
      chains={[Mainnet]}
      transports={{ [Mainnet.id]: http() }}
    >
      <Address format address="0xEcd0D12E21805803f70de03B72B1C162dB0898d9" />
    </WagmiWeb3ConfigProvider>
  );
}

这样，Ant Design Web3 组件就能直接连以太坊主网。

• 这是一段 React 组件代码，导出默认组件名为 Web3。

• 主要使用了两个库的组件/功能：

  • wagmi 提供底层的连接、请求和 hook（核心能力）。
  • web3-wagmi 在此之上提供 UI 友好的 Provider、组件和约定，简化在 Ant Design 应用中的集成工作。

• 目的：通过 WagmiWeb3ConfigProvider 配置 Wagmi 的区块链连接（仅主网），并在内部使用 Address 组件来美化地显示一个以太坊地址。

• 链与传输的绑定：chains 指定了要支持的链，transports 为各链提供底层传输实现。这里使用 HTTP 传输（RPC or HTTP）。

• 组件职责分离：

  • WagmiWeb3ConfigProvider：提供区块链连接上下文。
  • Address：专注于地址的格式化显示。

    6. 展示 NFT —— NFTCard 组件

在 web3.tsx 中增加：

import { Address, NFTCard } from "@ant-design/web3";

<NFTCard
  address="0xEcd0D12E21805803f70de03B72B1C162dB0898d9"
  tokenId={641}
/>

NFTCard 组件会从 0xEcd0D12E21805803f70de03B72B1C162dB0898d9 NFT 合约中获取 tokenId 为 641 的 NFT 信息，然后展示在页面上。

7. 总结

到这里，已经完成了： ✅ 初始化 React + Next.js 项目 ✅ 集成 Ant Design Web3 + wagmi ✅ 成功展示链上 NFT

本章节主要是对于Dapp开发的初步体验，下面将进入真正的实操技术以及合约开发交互。