RainbowKit快速集成多链钱包连接，我如何从“连不上”到“丝滑切换”

背景

上个月，我接手了一个多链DeFi聚合器前端的迭代任务。项目原本只支持以太坊主网，现在产品经理要求快速接入Arbitrum、Polygon和Optimism。核心需求很明确：用户进来，点一个按钮就能连接MetaMask、Coinbase Wallet等主流钱包，并且能在不同链之间无缝切换，查看不同链上的资产和协议。

时间紧，任务重。我评估了一下，自己从零实现一套完整的钱包连接、状态管理、链切换和错误处理逻辑，至少得花上一周，而且后续维护成本高。团队里之前用过wagmi，但主要是基础连接。这次我决定试试RainbowKit，因为它号称是"wagmi的最佳实践封装"，开箱即用，而且UI组件很漂亮。我的目标是在一天内搞定基础的多链连接框架。

问题分析

一开始，我的想法很简单：照着RainbowKit官方文档，安装、配置、把ConnectButton组件一扔，不就完事了？但现实很快给了我一巴掌。

我按照基础教程配好了，按钮是出来了，也能弹出钱包选择框。但第一个问题马上就来了：用户连接后，我需要在应用的其他地方（比如导航栏显示地址、资产页面）获取当前的连接状态和账户信息。我本能地想用wagmi的useAccount等hook，但发现状态有时不同步。点击断开连接后，UI上偶尔还会显示已连接的状态。

第二个问题是链的切换。我配置了多个链，但用户从MetaMask里手动切换了网络（比如从Ethereum切到Polygon），我的应用界面有时感知不到，还是显示旧链的信息，导致后续的合约调用全错在错误的链上。

我意识到，RainbowKit虽然封装了复杂性，但它和底层wagmi的状态流、以及和用户钱包扩展程序的实时通信，需要更细致的配置才能稳定工作。这不是"配完即走"，而是需要理解它们之间如何协同。

核心实现

第一步：项目初始化与依赖安装

首先，我创建了一个新的React + TypeScript项目（如果已有项目，则跳过创建）。RainbowKit需要wagmi作为底层依赖，并且需要配置对应的链信息。

# 创建新项目
npx create-react-app my-web3-app --template typescript
cd my-web3-app

# 安装核心依赖
npm install @rainbow-me/rainbowkit wagmi viem @tanstack/react-query

这里有个关键点 ：RainbowKit依赖于@tanstack/react-query（旧称react-query）来进行高效的状态管理和缓存。即使你不直接使用它，也必须安装，否则会报错。

第二步：配置Provider与支持的链

这是核心配置环节。我需要在应用的根组件（通常是index.tsx或App.tsx）外包一层RainbowKit和wagmi的Provider。重点在于wagmiConfig的生成，这里需要定义项目支持哪些链。

我决定先支持四个链：Ethereum, Polygon, Arbitrum, Optimism。

// App.tsx
import React from 'react';
import './App.css';
import '@rainbow-me/rainbowkit/styles.css'; // 导入RainbowKit默认样式
import {
  getDefaultConfig,
  RainbowKitProvider,
} from '@rainbow-me/rainbowkit';
import { WagmiProvider } from 'wagmi';
import {
  mainnet,
  polygon,
  arbitrum,
  optimism,
} from 'wagmi/chains';
import {
  QueryClientProvider,
  QueryClient,
} from '@tanstack/react-query';

// 1. 初始化QueryClient
const queryClient = new QueryClient();

// 2. 配置Wagmi
const config = getDefaultConfig({
  appName: 'MyMultiChainDeFiApp',
  projectId: 'YOUR_PROJECT_ID', // 需要去WalletConnect Cloud申请
  chains: [mainnet, polygon, arbitrum, optimism], // 明确声明支持的链
  ssr: false, // 如果不是Next.js等SSR框架，设为false
});

function App() {
  return (
    // 3. 用Provider层层包裹
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>
          {/* 你的应用组件 */}
          <div className="App">
            <h1>我的多链DeFi聚合器</h1>
            {/* 其他内容 */}
          </div>
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

export default App;

这里有个大坑 ：projectId不能乱填。RainbowKit使用WalletConnect v2协议，这个ID必须从WalletConnect Cloud网站免费注册并创建一个项目来获取。如果随便写一个字符串，钱包连接（尤其是WalletConnect和Coinbase Wallet）会静默失败，控制台错误信息也不明显，我排查了好久。

第三步：使用ConnectButton并获取全局状态

现在，我可以在任何子组件中使用RainbowKit提供的ConnectButton和wagmi的hooks了。我创建了一个Header.tsx组件来放置连接按钮，并展示连接状态。

// components/Header.tsx
import { ConnectButton } from '@rainbow-me/rainbowkit';
import { useAccount, useChainId, useSwitchChain } from 'wagmi';

export const Header = () => {
  // 使用wagmi的hooks获取全局状态
  const { address, isConnected, chain } = useAccount();
  const chainId = useChainId();
  const { switchChain } = useSwitchChain();

  return (
    <header>
      <nav>
        <div>我的DeFi应用</div>
        <div>
          {isConnected ? (
            <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
              {/* 显示当前网络 */}
              <span>网络: {chain?.name || `未知 (ID: ${chainId})`}</span>
              {/* 显示缩短的地址 */}
              <span>
                {address?.slice(0, 6)}...{address?.slice(-4)}
              </span>
              {/* RainbowKit提供的完整功能按钮 */}
              <ConnectButton showBalance={false} />
              {/* 一个自定义的链切换示例 */}
              <button onClick={() => switchChain({ chainId: polygon.id })}>
                切换到Polygon
              </button>
            </div>
          ) : (
            <ConnectButton />
          )}
        </div>
      </nav>
    </header>
  );
};

注意这个细节 ：useAccount、useChainId等hook的状态，与ConnectButton组件内部的状态是自动同步的，因为它们共享同一个wagmi配置。这就是为什么我们可以在应用任何地方可靠地获取连接信息。ConnectButton本身已经包含了连接、切换钱包、切换网络、查看详情、断开连接等所有功能的UI和逻辑。

第四步：处理链切换与状态同步

为了让应用能实时响应用户在钱包里手动切换网络的操作，我需要监听链的变化并更新UI。wagmi的useAccount返回的chain对象，以及useChainId hook，都是响应式的。但为了在链切换时执行一些副作用（比如更新合约实例、重新获取链上数据），我使用了useEffect。

// components/AssetDashboard.tsx
import { useEffect } from 'react';
import { useAccount, useChainId } from 'wagmi';

export const AssetDashboard = () => {
  const { chain, isConnected } = useAccount();
  const chainId = useChainId();

  useEffect(() => {
    if (!isConnected) return;

    console.log(`链已切换至: ${chain?.name} (ID: ${chainId})`);
    
    // 这里可以执行链切换后的副作用：
    // 1. 更新当前链的RPC Provider
    // 2. 更新合约实例的地址（如果不同链合约地址不同）
    // 3. 重新获取该链上的用户资产数据
    // 4. 更新UI上关于链的提示信息

    // 例如，重新获取资产
    fetchAssetsForChain(chainId);

  }, [chainId, isConnected, chain]); // 依赖chainId，当它变化时触发

  const fetchAssetsForChain = async (currentChainId: number) => {
    // 模拟根据链ID获取资产的函数
    console.log(`获取链 ${currentChainId} 上的资产...`);
    // ... 实际的数据获取逻辑
  };

  return (
    <div>
      <h2>资产总览</h2>
      <p>当前网络: <strong>{chain?.name || '未连接'}</strong></p>
      {/* 资产列表 */}
    </div>
  );
};

这里有个坑 ：chain对象可能为undefined（例如钱包连接了但未授权任何账户，或者是一些边缘情况）。所以在使用chain.name或chain.id时，最好使用可选链操作符?.或做空值判断，否则会导致页面渲染错误。

完整代码

以下是一个简化但可运行的核心集成示例，将所有关键部分放在一起。

// index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

// App.tsx
import './App.css';
import '@rainbow-me/rainbowkit/styles.css';
import {
  getDefaultConfig,
  RainbowKitProvider,
} from '@rainbow-me/rainbowkit';
import { WagmiProvider } from 'wagmi';
import {
  mainnet,
  polygon,
  arbitrum,
  optimism,
} from 'wagmi/chains';
import {
  QueryClientProvider,
  QueryClient,
} from '@tanstack/react-query';
import { Header } from './components/Header';
import { AssetDashboard } from './components/AssetDashboard';

const queryClient = new QueryClient();

// 注意：请替换为你在 WalletConnect Cloud 申请的 projectId
const projectId = 'YOUR_WALLETCONNECT_PROJECT_ID_HERE';

const config = getDefaultConfig({
  appName: 'MultiChainDemo',
  projectId: projectId,
  chains: [mainnet, polygon, arbitrum, optimism],
  ssr: false,
});

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>
          <div className="App">
            <Header />
            <main>
              <AssetDashboard />
              {/* 你的其他页面组件 */}
            </main>
          </div>
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

export default App;

// components/Header.tsx
import { ConnectButton } from '@rainbow-me/rainbowkit';
import { useAccount } from 'wagmi';

export const Header = () => {
  const { isConnected, address, chain } = useAccount();

  return (
    <header style={{ padding: '1rem', borderBottom: '1px solid #ccc', display: 'flex', justifyContent: 'space-between' }}>
      <h1>多链DeFi演示</h1>
      <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
        {isConnected && (
          <>
            <div>
              网络: <strong>{chain?.name}</strong>
            </div>
            <div>
              地址: <code>{address?.slice(0, 8)}...{address?.slice(-6)}</code>
            </div>
          </>
        )}
        <ConnectButton />
      </div>
    </header>
  );
};

// components/AssetDashboard.tsx
import { useEffect } from 'react';
import { useAccount, useChainId } from 'wagmi';

export const AssetDashboard = () => {
  const { chain, isConnected } = useAccount();
  const chainId = useChainId();

  useEffect(() => {
    if (!isConnected) {
      console.log('钱包未连接');
      return;
    }
    // 当链ID变化时，执行数据更新逻辑
    console.log(`[副作用] 检测到链变化，当前链ID: ${chainId}, 名称: ${chain?.name}`);
    // 在实际项目中，这里应调用一个函数来更新该链的资产数据
  }, [chainId, isConnected, chain]);

  return (
    <div style={{ padding: '2rem' }}>
      <h2>资产仪表板</h2>
      <p>这个组件会监听链切换。打开控制台查看日志。</p>
      <div>
        <p><strong>连接状态:</strong> {isConnected ? '已连接' : '未连接'}</p>
        <p><strong>当前网络:</strong> {chain?.name || 'N/A'}</p>
        <p><strong>链ID:</strong> {chainId || 'N/A'}</p>
      </div>
    </div>
  );
};

踩坑记录

1. WalletConnect ProjectId 无效导致静默失败：这是最大的坑。我一开始随便写了个字符串，MetaMask能连（因为它不走WalletConnect），但Coinbase Wallet和WalletConnect二维码死活没反应，控制台也没有明显错误。后来在RainbowKit的GitHub issue里看到，必须去WalletConnect Cloud创建项目获取真实ID。解决后一切正常。
2. 链ID不匹配导致切换失败 ：我自定义了一个测试链，它的id我设成了12345。当我调用switchChain({ chainId: 12345 })时，钱包弹窗提示切换，但RainbowKit内部状态没更新。后来发现，getDefaultConfig里chains数组必须包含这个链的定义，并且id要和钱包里添加的网络ID完全一致。本质是RainbowKit/wagmi需要知道你打算切换到的链的详细信息（RPC URL、区块浏览器等）。
3. Hydration错误（Next.js场景） ：在Next.js项目中，如果SSR开启，需要在getDefaultConfig里设置ssr: true，并且确保与钱包相关的组件只在客户端渲染（用useEffect或typeof window !== 'undefined'判断），否则会因为服务端和客户端初始渲染内容不一致而报错。虽然我这次是Create React App，但这是常见的坑。
4. 样式冲突：RainbowKit会注入一些全局样式，如果和你项目的现有CSS（比如用了CSS-in-JS库或重置样式表）冲突，可能会导致弹窗位置错乱或样式怪异。解决方法是检查元素，用更高特异性的CSS规则覆盖，或者利用RainbowKit提供的主题定制功能来适配。

小结

通过这次集成，我最大的收获是：RainbowKit + wagmi 确实能极大加速Web3前端连接层的开发，但"开箱即用"不等于"无需理解"。清晰配置支持的链、妥善管理WalletConnect ProjectId、理解状态hook的响应式原理，是保证多链连接稳定丝滑的关键。下一步，我可以深入研究RainbowKit的主题定制，让UI完全融入项目设计，并探索如何与更复杂的多链合约读写逻辑结合。