从v1到v3：wagmi版本升级完整迁移指南和重大变更解析

作为以太坊开发中最受欢迎的React Hooks库，wagmi在v1到v3的演进中经历了革命性的架构重构。本指南将详细解析每个版本的核心变更，帮助您顺利完成迁移，享受更强大的开发体验。🚀

wagmi是一个专为以太坊开发的React Hooks库，提供简洁的API来连接钱包、读取链上数据、发送交易等操作。通过版本升级，您将获得更好的TypeScript支持、更小的包体积和更流畅的开发体验。

为什么需要升级到最新版本？

性能提升 ✨ - wagmi v3相比v1包体积减少了40%，启动速度提升50% 开发体验 🛠️ - 更好的TypeScript支持和更直观的API设计 功能增强 ⚡ - 原生多链支持和更强大的账户管理

wagmi v1到v2：架构重构的重大升级

核心依赖变更

在v2中，TanStack Query从内部依赖变为对等依赖，这意味着您需要显式设置查询客户端：

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WagmiProvider } from 'wagmi'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {/* 您的应用组件 */}
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Hooks API重大变更

突变函数参数位置变更 - 不再支持直接向hooks传递参数，必须使用突变函数：

// v1方式 - 已废弃
const { signMessage } = useSignMessage({
  message: 'Hello World',
})

// v2正确方式
const { signMessage } = useSignMessage()
// 使用时传递参数
signMessage({ message: 'Hello World' })

连接器API全面更新

所有连接器从类实例化变为函数调用：

// v1 - 已废弃
import { MetaMaskConnector } from 'wagmi/connectors/metaMask'
const connector = new MetaMaskConnector()

// v2正确方式
import { injected } from 'wagmi/connectors'
const connector = injected({ target: 'metaMask' })

wagmi v2到v3：依赖管理的现代化

连接器依赖变为可选对等依赖

在v3中，所有连接器依赖都变为可选对等依赖。这意味着如果您使用特定连接器，需要手动安装其依赖：

Coinbase钱包连接器：

pnpm add @coinbase/wallet-sdk

MetaMask连接器：

pnpm add @metamask/sdk

Safe连接器：

pnpm add @safe-global/safe-apps-provider @safe-global/safe-apps-sdk

配置系统的演进

createConfig参数简化

v3中移除了多个冗余参数，配置变得更加简洁：

import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
})

迁移最佳实践

1. 逐步迁移策略

• 先升级到v2，解决所有破坏性变更
• 再升级到v3，处理依赖管理变更
• 利用TypeScript编译器检查未处理的变更

2. 测试覆盖保障

• 在迁移前后运行完整的测试套件
• 特别关注钱包连接和交易发送功能

3. 回滚计划

• 确保有完整的代码备份
• 准备快速回滚到稳定版本

常见问题解答

Q: 升级后我的应用会变慢吗？ A: 不会！v3相比v1有显著的性能提升

Q: 需要重写多少代码？ A: 大部分变更可以通过查找替换快速完成

Q: 支持哪些框架？ A: wagmi支持React、Vue、Next.js、Nuxt等主流框架

总结

通过本指南，您已经了解了从wagmi v1到v3的核心变更和迁移要点。虽然版本升级涉及一些破坏性变更，但带来的性能提升和开发体验改进是值得的。开始您的迁移之旅，体验更现代化的以太坊开发！🎯

记住：wagmi v2应该是最后一个需要如此多破坏性变更的主要版本。未来的升级将更加平滑，让您专注于构建出色的去中心化应用。

本文基于wagmi官方迁移文档整理，确保信息的准确性和实用性。