Next.js 14 + wagmi v2 构建 NFT 市场：从列表渲染到实时更新的完整链路

竹林818
9 阅读1分钟

背景

上个月，我接手了一个新的 Web3 项目：为一个基于 Base 链的 NFT 系列开发一个轻量级的交易市场前端。核心需求很简单：展示该系列的所有 NFT，显示每个 NFT 的当前挂单价格，并且当用户购买或取消挂单时，页面上的信息要能实时更新，无需手动刷新。

技术栈选型很明确：Next.js 14（App Router）、TypeScript、Tailwind CSS，以及 Web3 交互的核心——wagmi v2 和 viem。我心想，这不过是把链上数据读出来，监听几个事件，再渲染成列表，用 useAccount 和 useReadContract 不就搞定了吗？结果，从第一行代码开始，坑就一个接一个地来了。

问题分析

我的初始思路非常直接：在页面组件里，用 wagmi 的 useReadContract 读取 NFT 合约的 totalSupply，然后循环获取每个 Token 的元数据和挂单信息，最后用 useEffect 监听 ListingUpdated 和 Transfer 事件来触发数据重拉。

但一上手就发现了几个致命问题：

  1. 水合（Hydration）错误：在服务端组件（Server Component）中直接使用 useAccount 或 useReadContract 会导致错误，因为这些钩子依赖于浏览器环境。
  2. 性能灾难：如果我有 1000 个 NFT，难道要发起 1000+ 次 RPC 调用吗？页面加载会慢到无法接受。
  3. 实时更新失效：简单地用 useEffect 监听事件，在用户切换钱包或断开连接时，监听器会混乱，导致更新不及时或重复更新。
  4. 状态同步难题：交易（购买、挂单）提交后，如何优雅地等待链上确认，并立即更新 UI，而不是等用户手动刷新？

最初的方案完全走不通。我意识到，必须把服务端初始渲染、客户端状态管理、批量数据获取和事件驱动更新这几个环节拆解开，设计一个更清晰的架构。

核心实现

1. 架构分层：服务端获取初始数据

首先，我放弃了在页面组件里直接调用 Web3 钩子获取所有数据的想法。对于 NFT 列表这种相对静态的初始数据，应该在服务端获取。我创建了一个服务端函数，使用 Viem 的公共客户端（Public Client）来读取链上数据。

关键点：在 App Router 中，我们可以在 Server Component 或 Server Action 里直接与区块链交互，无需钱包连接。这完美解决了初始渲染的问题。

// app/api/nfts/route.ts
import { createPublicClient, http } from 'viem';
import { base } from 'viem/chains';

// 初始化一个不需要钱包的公共客户端
const publicClient = createPublicClient({
  chain: base,
  transport: http(process.env.NEXT_PUBLIC_RPC_URL),
});

// NFT 合约 ABI 片段
const NFT_ABI = [
  {
    name: 'totalSupply',
    type: 'function',
    stateMutability: 'view',
    inputs: [],
    outputs: [{ type: 'uint256' }],
  },
  {
    name: 'tokenURI',
    type: 'function',
    stateMutability: 'view',
    inputs: [{ name: 'tokenId', type: 'uint256' }],
    outputs: [{ type: 'string' }],
  },
] as const;

// 市场合约 ABI 片段
const MARKET_ABI = [
  {
    name: 'listings',
    type: 'function',
    stateMutability: 'view',
    inputs: [{ name: 'tokenId', type: 'uint256' }],
    outputs: [
      { name: 'seller', type: 'address' },
      { name: 'price', type: 'uint256' },
      { name: 'isActive', type: 'bool' },
    ],
  },
] as const;

export async function GET() {
  try {
    const totalSupply = await publicClient.readContract({
      address: process.env.NEXT_PUBLIC_NFT_CONTRACT as `0x${string}`,
      abi: NFT_ABI,
      functionName: 'totalSupply',
    });

    const nftDataPromises = [];
    // 注意：这里用 Number 转换只适用于总量不大的情况，真实项目需考虑 BigInt
    for (let i = 0; i < Number(totalSupply); i++) {
      const promise = Promise.all([
        // 获取元数据 URI
        publicClient.readContract({
          address: process.env.NEXT_PUBLIC_NFT_CONTRACT as `0x${string}`,
          abi: NFT_ABI,
          functionName: 'tokenURI',
          args: [BigInt(i)],
        }),
        // 获取挂单信息
        publicClient.readContract({
          address: process.env.NEXT_PUBLIC_MARKET_CONTRACT as `0x${string}`,
          abi: MARKET_ABI,
          functionName: 'listings',
          args: [BigInt(i)],
        }),
      ]).then(([tokenURI, listing]) => ({
        tokenId: i,
        tokenURI,
        listing,
      }));
      nftDataPromises.push(promise);
    }

    const nfts = await Promise.all(nftDataPromises);
    return Response.json({ nfts });
  } catch (error) {
    console.error('Failed to fetch NFTs:', error);
    return Response.json({ error: 'Fetch failed' }, { status: 500 });
  }
}

这里有个坑：直接循环调用 RPC 在 NFT 数量多时确实慢。在生产环境中，你应该考虑让合约本身返回批量数据，或者使用 The Graph 这类索引服务。我这里为了演示核心流程，先采用简单循环。

2. 客户端状态与实时更新

服务端提供了初始数据，但购买、挂单等交互后的实时更新必须在客户端处理。我创建了一个客户端组件 NftList，它接收服务端的初始数据，并负责管理动态状态。

实时更新的核心是 监听链上事件。wagmi v2 提供了 useWatchContractEvent 钩子，但直接用在列表组件里会导致每个 NFT 卡片都创建一个监听器，性能极差。我的方案是：在父级组件只监听市场合约的全局事件。

// components/nft-list.tsx
'use client';

import { useEffect, useState } from 'react';
import { useWatchContractEvent } from 'wagmi';
import { NftCard } from './nft-card';

// 市场合约 ABI 事件片段
const MARKET_EVENT_ABI = [
  {
    type: 'event',
    name: 'ListingUpdated',
    inputs: [
      { indexed: true, name: 'tokenId', type: 'uint256' },
      { indexed: false, name: 'seller', type: 'address' },
      { indexed: false, name: 'price', type: 'uint256' },
      { indexed: false, name: 'isActive', type: 'bool' },
    ],
  },
] as const;

interface NftListProps {
  initialNfts: Array<{
    tokenId: number;
    tokenURI: string;
    listing: [string, bigint, boolean];
  }>;
}

export function NftList({ initialNfts }: NftListProps) {
  // 使用服务端数据初始化状态
  const [nfts, setNfts] = useState(initialNfts);

  // 关键：监听全局的 ListingUpdated 事件
  useWatchContractEvent({
    address: process.env.NEXT_PUBLIC_MARKET_CONTRACT as `0x${string}`,
    abi: MARKET_EVENT_ABI,
    eventName: 'ListingUpdated',
    onLogs(logs) {
      console.log('ListingUpdated logs:', logs);
      // 当事件触发时，更新对应 NFT 的挂单信息
      logs.forEach((log) => {
        const { tokenId, price, isActive } = log.args;
        if (tokenId !== undefined) {
          setNfts((prev) =>
            prev.map((nft) =>
              nft.tokenId === Number(tokenId)
                ? {
                    ...nft,
                    listing: [log.args.seller || '0x', price || 0n, isActive || false],
                  }
                : nft
            )
          );
        }
      });
    },
  });

  // 一个手动刷新函数，用于在交易确认后主动触发（作为兜底）
  const refreshData = async () => {
    const res = await fetch('/api/nfts');
    const data = await res.json();
    if (data.nfts) setNfts(data.nfts);
  };

  return (
    <div>
      <button onClick={refreshData} className="mb-4 p-2 bg-gray-200 rounded">
        手动刷新数据
      </button>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        {nfts.map((nft) => (
          <NftCard key={nft.tokenId} nft={nft} onActionSuccess={refreshData} />
        ))}
      </div>
    </div>
  );
}

注意这个细节：useWatchContractEvent 的回调函数中，log.args 的类型可能是 undefined，必须做防御性判断，否则 TypeScript 会报错，运行时也可能崩溃。

3. 交易交互与乐观更新

用户点击“购买”时，如果等到交易上链确认（可能十几秒）才更新 UI，体验会很差。我采用了 乐观更新（Optimistic Update） 的策略：先立即更新本地状态，假设交易会成功；如果交易失败，再回滚状态。

// components/nft-card.tsx
'use client';

import { useState } from 'react';
import { useAccount, useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
import { parseEther } from 'viem';

interface NftCardProps {
  nft: {
    tokenId: number;
    tokenURI: string;
    listing: [string, bigint, boolean];
  };
  onActionSuccess?: () => void;
}

export function NftCard({ nft, onActionSuccess }: NftCardProps) {
  const { address } = useAccount();
  const [isUpdating, setIsUpdating] = useState(false);
  const { data: hash, writeContract, error } = useWriteContract();
  const { isLoading: isConfirming } = useWaitForTransactionReceipt({ hash });

  const [seller, price, isActive] = nft.listing;

  const handleBuy = async () => {
    if (!address || !isActive) return;

    setIsUpdating(true); // 开始乐观更新
    // 这里可以立即调用父组件传递的回调，或者用状态管理更新本地列表
    // 为了简化，我们假设父组件会通过事件监听更新，这里只处理自身加载状态

    try {
      writeContract({
        address: process.env.NEXT_PUBLIC_MARKET_CONTRACT as `0x${string}`,
        abi: [
          {
            name: 'buyToken',
            type: 'function',
            stateMutability: 'payable',
            inputs: [{ name: 'tokenId', type: 'uint256' }],
            outputs: [],
          },
        ] as const,
        functionName: 'buyToken',
        args: [BigInt(nft.tokenId)],
        value: price,
      });
    } catch (err) {
      console.error('Buy failed:', err);
      setIsUpdating(false); // 回滚乐观更新
    }
  };

  // 交易确认后的处理
  useEffect(() => {
    if (hash && !isConfirming) {
      console.log('Transaction confirmed!');
      setIsUpdating(false);
      onActionSuccess?.(); // 通知父组件刷新数据
    }
  }, [hash, isConfirming, onActionSuccess]);

  return (
    <div className="border p-4 rounded-lg shadow">
      <img src={`https://ipfs.io/ipfs/${nft.tokenURI.split('://')[1]}`} alt={`NFT ${nft.tokenId}`} className="w-full h-48 object-cover rounded" />
      <div className="mt-2">
        <p className="font-bold">Token ID: {nft.tokenId}</p>
        <p>Price: {price ? parseFloat(parseEther(price.toString()).toString()).toFixed(4)} ETH</p>
        <p>Status: {isActive ? 'For Sale' : 'Not Listed'}</p>
      </div>
      {isActive && address !== seller && (
        <button
          onClick={handleBuy}
          disabled={isUpdating || isConfirming}
          className={`mt-2 w-full py-2 rounded ${isUpdating || isConfirming ? 'bg-gray-400' : 'bg-blue-500 hover:bg-blue-600 text-white'}`}
        >
          {isUpdating || isConfirming ? 'Processing...' : 'Buy Now'}
        </button>
      )}
      {error && <p className="text-red-500 text-sm mt-1">Error: {error.message}</p>}
    </div>
  );
}

这里有个大坑：乐观更新时，你更新的状态必须与链上最终状态一致。比如购买后，NFT 的卖家会变，挂单状态会变为 false。如果只是简单地把 isActive 设为 false，但卖家地址没变，就会与链上数据不一致。最稳妥的方式是，在交易发送后，立即用事件监听来更新，或者等确认后触发一次数据重拉。

4. 页面集成与配置

最后，将服务端数据获取和客户端组件在页面中组装起来。页面是服务端组件，它获取数据并传递给客户端组件。

// app/page.tsx
import { NftList } from '@/components/nft-list';

async function getInitialNfts() {
  // 在构建时或请求时从 API 路由获取数据
  const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/nfts`, {
    // 根据需求配置缓存
    // next: { revalidate: 60 }, // ISR: 每60秒重新验证
    cache: 'no-store', // 每次请求都获取最新数据
  });
  if (!res.ok) {
    throw new Error('Failed to fetch NFTs');
  }
  return res.json();
}

export default async function HomePage() {
  const data = await getInitialNfts();

  return (
    <main className="container mx-auto p-4">
      <h1 className="text-3xl font-bold mb-6">NFT Marketplace</h1>
      {/* 将服务端数据作为 prop 传递给客户端组件 */}
      <NftList initialNfts={data.nfts || []} />
    </main>
  );
}

同时，需要在项目根目录配置 wagmi 的 Provider。注意 Next.js 14 App Router 中，Provider 必须是客户端组件。

// app/providers.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider, createConfig, http } from 'wagmi';
import { base } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

const queryClient = new QueryClient();

const config = createConfig({
  chains: [base],
  connectors: [injected()],
  transports: {
    [base.id]: http(process.env.NEXT_PUBLIC_RPC_URL),
  },
});

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </WagmiProvider>
  );
}

// app/layout.tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';
import { Providers } from './providers';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'NFT Marketplace',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

完整代码结构

项目的主要文件结构如下：

my-nft-marketplace/
├── app/
│   ├── api/
│   │   └── nfts/
│   │       └── route.ts          # 服务端 API，获取初始 NFT 数据
│   ├── layout.tsx                # 根布局，包含 Providers
│   ├── page.tsx                  # 主页（服务端组件）
│   └── providers.tsx             # Wagmi & React Query Provider
├── components/
│   ├── nft-list.tsx              # NFT 列表客户端组件（核心状态与事件监听）
│   └── nft-card.tsx              # 单个 NFT 卡片组件（交易交互）
├── .env.local                    # 环境变量（合约地址、RPC URL）
└── package.json

踩坑记录

  1. NEXT_PUBLIC_ 变量在服务端为 undefined：我一开始把合约地址放在 .env.local 但没加 NEXT_PUBLIC_ 前缀，导致在服务端 API 路由中读取不到。解决：确保所有需要在浏览器和服务端共享的变量都以 NEXT_PUBLIC_ 开头。
  2. useWatchContractEvent 监听不到事件：我一开始把监听器放在 NftCard 组件里，结果组件卸载时监听器也被移除了，而且重复创建。解决：将全局事件监听提升到父组件（NftList），并确保合约地址和 ABI 正确。
  3. BigInt 序列化错误：从服务端 API 返回的数据中包含 bigint 类型的价格，直接 JSON.stringify 会报错。解决：在服务端将 bigint 转换为字符串，或者在客户端使用 Viem 的 parseEther 等工具处理。我在 API 路由中返回了原始数据，在组件内处理转换。
  4. 交易确认后状态不同步：用户购买成功后，列表里该 NFT 的 isActive 状态变了，但卖家地址还是旧的。解决：这是因为我的乐观更新逻辑不完整。最终我选择依赖 useWatchContractEvent 的事件监听作为主要更新源，手动刷新作为兜底，保证了数据与链上严格同步。

小结

这套方案的核心收获是 “服务端初始化，客户端维护动态状态，事件驱动更新”。它既保证了首屏加载速度，又实现了流畅的实时交互。对于更复杂的场景，比如分页、筛选、多链支持，还可以在此基础上扩展，例如引入状态管理库来集中管理 NFT 数据，或者用 The Graph 替代批量 RPC 调用。Web3 前端开发就是这样，每一个需求都在逼你更深入地理解数据流和链上链下的同步逻辑。

avatar
文章
阅读
粉丝