migrating-an-onchainkit-app

OnchainKit 迁移技能

将应用从 @coinbase/onchainkit 迁移到独立的 wagmi/viem 组件，不再依赖 OnchainKit。

开始之前

在项目根目录创建 mistakes.md 文件：

# Migration Mistakes & Learnings

Track errors, fixes, and lessons learned during OnchainKit migration.

## Errors

## Lessons Learned

在整个迁移过程中，将每个错误、修复方案和经验教训追加到此文件中。此文件有助于持续改进该技能。

迁移工作流

迁移必须按以下顺序进行。请勿跳过步骤。

步骤 1：检测

扫描项目，了解当前对 OnchainKit 的使用情况：

1. 搜索所有文件中的 @coinbase/onchainkit 导入
2. 确认使用了哪些组件：
   • Provider：OnchainKitProvider（使用 OnchainKit 时始终存在）
   • Wallet：Wallet、ConnectWallet、WalletDropdown、WalletModal、Connected
   • Transaction：Transaction、TransactionButton、TransactionStatus
   • 其他：Identity、Avatar、Name、Address、Swap、Checkout 等
3. 检查 package.json 中是否已有 wagmi、viem、@tanstack/react-query 依赖
4. 确认项目采用的样式方案（Tailwind、CSS Modules、styled-components 等）
5. 继续操作前，向用户报告检查结果

步骤 2：迁移 Provider（始终首先进行）

阅读 references/provider-migration.md，了解详细说明和代码。

摘要：

1. 确保已安装 wagmi、viem 和 @tanstack/react-query
2. 创建 wagmi-config.ts，配置链和连接器
3. 用 WagmiProvider + QueryClientProvider 替换 OnchainKitProvider
4. 移除 @coinbase/onchainkit/styles.css 导入
5. 移除布局文件中的任何 SafeArea 或 MiniKit 导入

验证关卡：运行 npm run build（或项目的构建命令）。必须通过后才能继续。如果失败，请修复错误并记录到 mistakes.md。

步骤 3：迁移 Wallet（在 Provider 之后）

阅读 references/wallet-migration.md，了解详细说明和代码。

摘要：

1. 使用 wagmi hooks（useAccount、useConnect、useDisconnect）创建 WalletConnect 组件
2. 组件包含一个提供以下钱包选项的模态框：Base Account、Coinbase Wallet、MetaMask
3. 连接后显示截断的地址和断开连接按钮
4. 替换所有 OnchainKit 钱包导入和组件用法

验证关卡：运行 npm run build。必须通过后才能继续。将任何错误记录到 mistakes.md。

步骤 4：迁移 Transaction（在 Wallet 之后）

阅读 references/transaction-migration.md，了解详细说明和代码。

摘要：

1. 检查现有 <Transaction /> 组件上的 chainId 属性——将任何缺失的链添加到 wagmi-config.ts
2. 使用 wagmi hooks（useWriteContract、useWaitForTransactionReceipt、useSwitchChain）创建 TransactionForm 组件
3. 组件处理完整生命周期：空闲、等待钱包确认、链上确认中、成功、错误
4. 替换所有 OnchainKit 交易导入（Transaction、TransactionButton、TransactionStatus、TransactionSponsor 等）
5. 更新 calls 数组格式——使用 address、abi、functionName、args，并正确添加 as const 类型
6. 将 onStatus 回调映射到新的生命周期状态名称（init、pending、confirmed、success、error）

验证关卡：运行 npm run build。必须通过后才能继续。将任何错误记录到 mistakes.md。

步骤 5：清理

1. 搜索是否仍有 @coinbase/onchainkit 导入——应当全部移除
2. 可选择从 package.json 依赖中移除 @coinbase/onchainkit
3. 运行最终的 npm run build，验证一切正常
4. 在 mistakes.md 中补充最终经验教训

故障排查

提供方迁移后构建失败

• 缺少依赖项：确保已安装 wagmi、viem、@tanstack/react-query
• wagmi 配置存在类型错误：检查 chains 数组至少包含一条链，并且 transports 中有对应条目
• 缺少 "use client"：提供方和钱包组件都必须包含 "use client" 指令

MetaMask SDK react-native 警告

• 警告 Can't resolve '@react-native-async-storage/async-storage' 在 Web 构建中无害。该警告来自 MetaMask SDK，不会影响功能。

钱包无法连接

• 确认 wagmi 配置中配置了正确的连接器
• 检查在使用任何钱包钩子之前，WagmiProvider 是否已包裹组件树
• 确保 QueryClientProvider 位于 WagmiProvider 内部

交易收据一直处于待处理状态

• 症状：交易哈希已显示，交易已在链上确认，但 UI 一直卡在 "Transaction in progress..."
• 原因：由于交易所在的链缺少在 wagmi 配置的 chains 和 transports 中，useWaitForTransactionReceipt 没有 RPC 可用于轮询
• 修复方法：(1) 将目标链添加到 wagmi-config.ts 的 chains 数组和 transports 对象中。(2) 始终将 chainId 传给 useWaitForTransactionReceipt({ hash, chainId })，以便轮询正确的链

交易发送到了错误的链

• TransactionForm 会自动切换链，但目标链必须存在于 wagmi 配置的 chains 数组和 transports 对象中
• 常见情况：为测试网交易添加 baseSepolia（chainId 84532）

Next.js 页面导出限制

• Next.js 仅允许页面文件导出特定的命名导出。从页面文件导出合约调用数组或 ABI 常量会导致构建错误
• 修复方法：将它们声明为非导出的 const，或移至单独的模块

交易迁移后出现 ABI 类型错误

• 内联定义 ABI 时，在数组上使用 as const 以正确推断类型
• 为 type: 'function' 和 stateMutability: 'nonpayable' 等单个字段标记 as const

检测到现有 wagmi 配置

• 如果项目已经使用 WagmiProvider 包裹组件，不要再添加一个
• 只需更新现有的 wagmi 配置，加入所需的连接器
• OnchainKit 的提供方会检测并遵循现有的 wagmi 提供方，独立配置也应如此

重要说明

• 始终直接使用 wagmi 和 viem。切勿从 @coinbase/onchainkit 导入。
• baseAccount 连接器来自 wagmi/connectors，而不是单独的包。
• wagmi-config.ts 必须包含应用进行交易所涉及的每条链。如果原来的 OnchainKit <Transaction chainId={X} /> 使用了特定链，该链必须同时存在于 chains 和 transports 中。否则，useWaitForTransactionReceipt 将永远卡住。
• 如果项目使用 Tailwind，请为组件使用 Tailwind 类。如果没有，请改用内联样式或项目现有的样式方案（例如 CSS Modules）。
• 不要从 Next.js 页面文件导出合约调用数组、ABI 常量或其他非页面值。请使用非导出常量或单独的模块。
• 如果需要了解特定组件的内部工作方式，请检查 node_modules/@coinbase/onchainkit/src/ 中的 OnchainKit 源代码。