RainbowKit 配置单链时出现 ChainNotConfiguredError 问题解析

在使用 RainbowKit 构建 Web3 应用时，开发者可能会遇到一个特定场景下的配置问题：当仅配置主网（mainnet）或某些特定链时，系统会抛出 ChainNotConfiguredError: Chain not configured 错误。这个问题看似简单，但背后涉及 RainbowKit 和 wagmi 的深层交互机制。

问题现象

开发者在使用 RainbowKit 2.1.3 和 wagmi 2.10.9 版本时，发现以下配置会导致应用崩溃：

const config = getDefaultConfig({
  ssr: true,
  appName: 'App Name',
  projectId: 'WALLET_CONNECT_PROJECT_ID',
  chains: [mainnet],  // 仅配置主网
  wallets,
});

错误表现为：

1. 应用完全无法运行
2. 控制台显示 ChainNotConfiguredError 错误
3. 有趣的是，当将主网替换为 Arbitrum 等其他链时，却能正常工作

问题根源分析

经过深入排查，这个问题源于几个关键因素：

1. 配置位置不当：开发者最初将 getDefaultConfig 放在了 React 组件内部，这会导致每次渲染都重新创建配置，可能引发意外行为。

2. 单链配置的特殊性：RainbowKit 对单链配置（特别是主网）的处理存在边界情况，当仅配置主网时，内部的状态管理可能出现异常。

3. 空数组限制：RainbowKit 目前不允许传入空数组作为 chains 参数，这限制了动态链配置的可能性。

解决方案

针对这个问题，我们推荐以下最佳实践：

1. 正确放置配置：将 RainbowKit 配置移出组件，放在模块顶层：

const config = getDefaultConfig({
  ssr: true,
  appName: 'App Name',
  projectId: 'WALLET_CONNECT_PROJECT_ID',
  chains: [mainnet, arbitrum],  // 至少配置两条链
  wallets,
});

function RainbowKitProvider({ children }) {
  // 组件实现
}

2. 多链配置策略：即使你只需要主网，也建议至少配置两条链作为临时解决方案。

3. SessionProvider 集成：如果使用 NextAuth 等认证方案，确保添加 SessionProvider：

<SessionProvider>
  <WagmiProvider config={config}>
    {/* 其他Provider */}
  </WagmiProvider>
</SessionProvider>

进阶建议

对于希望实现更灵活链管理的开发者，可以考虑以下方案：

1. 动态链加载：通过 API 或配置文件动态加载链配置，避免硬编码。

2. 错误边界处理：在应用顶层添加错误边界，优雅处理链配置错误。

3. 自定义链提示：通过扩展 RainbowKit 组件，实现"无可用网络"等友好提示。

总结

RainbowKit 作为优秀的 Web3 开发工具库，在大多数场景下表现良好，但在单链配置这种边界情况下需要特别注意。开发者应当遵循官方推荐的最佳实践，将配置置于组件外部，并考虑多链兼容性设计。随着 RainbowKit 的持续迭代，这类边界情况有望得到进一步改善。