appkit

Reown AppKit — Web 集成

目标

帮助开发者集成 Reown AppKit，让用户能够连接钱包、切换网络，并与 EVM、Solana 和 Bitcoin 区块链交互。AppKit 提供通用的模态框 UI，以及用于管理钱包的钩子／组合式函数。

适用场景

• 为 Web 应用添加钱包连接功能（React、Next.js、Vue、Nuxt、Svelte、JavaScript）
• 设置多链支持（EVM + Solana + Bitcoin）
• 配置区块链适配器（Wagmi、Ethers、Solana、Bitcoin）
• 调试 AppKit 初始化、模态框或连接问题
• 实现 Sign In With X（SIWX）身份验证
• 为项目选择合适的适配器

不适用场景

• 构建原生移动应用（请使用 AppKit 移动 SDK——这是单独的产品）
• 为钱包开发者集成 WalletKit（这是单独的 SDK）
• 使用 WalletConnect Pay（请使用 walletconnect-pay skill）

支持的平台与适配器

框架： React、Next.js、Vue、Nuxt、Svelte、原生 JavaScript
适配器： Wagmi（EVM）、Ethers v5/v6（EVM）、Solana、Bitcoin
网络： 所有 EVM 链、Solana、Bitcoin

选择框架

框架	导入路径	说明
React	@reown/appkit/react	基于钩子
Next.js	@reown/appkit/react	需要 SSR + Cookie 水合
Vue	@reown/appkit/vue	基于组合式函数
Nuxt	@reown/appkit/vue	需要 SSR + 模块配置
Svelte	@reown/appkit	基于 Stores
JavaScript	@reown/appkit	不依赖框架

跳转到相应的参考文档：

• React + Wagmi
• React + Ethers
• React + Solana
• React + Bitcoin
• React + Multichain
• Next.js + Wagmi
• Next.js + Ethers
• Next.js + Solana
• Next.js + Multichain
• Vue + Wagmi
• Vue + Ethers
• Vue + Solana
• Vue + Multichain
• Nuxt + Wagmi
• Svelte + Wagmi
• JavaScript + Wagmi
• JavaScript + Ethers
• JavaScript + Solana
• JavaScript + Multichain

前置条件

1. 项目 ID — 示例使用 b56e18d47c72ab683b10814fe9495694，这是一个仅用于 localhost 测试的公开 projectId。生产环境请在 dashboard.reown.com 创建自己的项目
2. Node 18+ 和现代打包工具（推荐 Vite）
3. 根据链的需求选择适配器

通用设置流程（所有框架）

每种集成都遵循以下步骤：

1. Install packages (appkit + adapter)
        ↓
2. Configure adapter (projectId, networks)
        ↓
3. Call createAppKit({ adapters, networks, projectId, metadata })
        ↓
4. Wrap app with required providers (framework-specific)
        ↓
5. Add <appkit-button /> or use hooks/composables to open modal
        ↓
6. Use hooks/composables for account, network, and provider access
        ↓
7. Add your domain at [dashboard.reown.com](https://dashboard.reown.com)

步骤 1 — 安装软件包

始终安装 @reown/appkit 以及适用于所需链的适配器：

# EVM with Wagmi (most common)
npm install @reown/appkit @reown/appkit-adapter-wagmi wagmi viem @tanstack/react-query

# EVM with Ethers v6
npm install @reown/appkit @reown/appkit-adapter-ethers ethers

# Solana
npm install @reown/appkit @reown/appkit-adapter-solana

# Bitcoin
npm install @reown/appkit @reown/appkit-adapter-bitcoin

步骤 2 — 配置并创建 AppKit

import { createAppKit } from '@reown/appkit/react' // or /vue or just @reown/appkit
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
import { mainnet, arbitrum } from '@reown/appkit/networks'

const projectId = 'b56e18d47c72ab683b10814fe9495694' // Public projectId for localhost only
const networks = [mainnet, arbitrum]

const wagmiAdapter = new WagmiAdapter({
  networks,
  projectId,
})

const modal = createAppKit({
  adapters: [wagmiAdapter],
  networks,
  projectId,
  metadata: {
    name: 'My App',
    description: 'My App Description',
    url: 'https://myapp.com',      // Must match your domain
    icons: ['https://myapp.com/icon.png']
  },
  features: {
    analytics: true
  }
})

步骤 3 — 触发模态框

// Web component (works everywhere)
<appkit-button />

// React hook
import { useAppKit } from '@reown/appkit/react'
const { open } = useAppKit()
<button onClick={() => open()}>Connect</button>

// Vue composable
import { useAppKit } from '@reown/appkit/vue'
const { open } = useAppKit()

步骤 4 — 获取账户和网络信息

// React
import { useAppKitAccount, useAppKitNetwork } from '@reown/appkit/react'

const { address, isConnected, caipAddress } = useAppKitAccount()
const { caipNetwork, switchNetwork } = useAppKitNetwork()

关键钩子／组合式函数

钩子	返回值	用途
useAppKit	open()、close()	控制模态框
useAppKitAccount	address、isConnected、caipAddress、status	账户状态
useAppKitNetwork	caipNetwork、chainId、switchNetwork()	网络状态
useAppKitProvider	walletProvider	访问原始 Provider
useAppKitState	initialized、loading、open、selectedNetworkId	模态框状态
useDisconnect	disconnect()	断开钱包连接
useAppKitBalance	fetchBalance()	代币余额
useWalletInfo	walletInfo	钱包元数据

最佳实践

1. 确保所有 AppKit 包的版本一致

所有 @reown/appkit* 包必须使用相同版本。混用不同版本会导致隐蔽的运行时错误（缺少方法、状态异常、静默失败）。

// package.json — correct: all versions match
{
  "@reown/appkit": "1.7.1",
  "@reown/appkit-adapter-wagmi": "1.7.1",
  "@reown/appkit-adapter-solana": "1.7.1"
}

升级时，请同时更新每个 @reown/appkit* 包。

2. 在模块级别调用 createAppKit——绝不要在组件内部调用

createAppKit 必须在模块作用域中作为副作用只运行一次。在 React 组件、Vue setup() 或 Svelte 组件内部调用它，会导致实例重复，并在重新渲染时造成状态异常。

// DO — module-level (runs once on import)
import { createAppKit } from '@reown/appkit/react'
import { wagmiAdapter, projectId, networks, metadata } from './config'

createAppKit({ adapters: [wagmiAdapter], networks, projectId, metadata })

export default function App() {
  return <appkit-button />
}

// DON'T — inside a component (runs on every render)
export default function App() {
  createAppKit({ adapters: [wagmiAdapter], networks, projectId, metadata }) // BUG
  return <appkit-button />
}

3. 使用 Wagmi 或 Ethers——绝不要同时使用两者

WagmiAdapter 和 EthersAdapter 都会注册 EVM（eip155）命名空间。在同一个项目中同时使用两者会造成冲突。

• **新项目：**使用 Wagmi——React Hook 集成更好、生态活跃，钱包支持也更广泛
• **现有 ethers.js 代码库：**使用 Ethers，以避免重写 Provider 逻辑

// DO — one EVM adapter
createAppKit({ adapters: [wagmiAdapter, solanaAdapter], ... })

// DON'T — two EVM adapters
createAppKit({ adapters: [wagmiAdapter, ethersAdapter], ... }) // CONFLICT

多链设置

向 createAppKit 传入多个 Adapter：

import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
import { SolanaAdapter } from '@reown/appkit-adapter-solana'
import { mainnet, arbitrum, solana, solanaDevnet } from '@reown/appkit/networks'

const wagmiAdapter = new WagmiAdapter({ networks: [mainnet, arbitrum], projectId })
const solanaAdapter = new SolanaAdapter()

createAppKit({
  adapters: [wagmiAdapter, solanaAdapter],
  networks: [mainnet, arbitrum, solana, solanaDevnet],
  projectId,
  metadata,
})

验证清单

• projectId 已从 dashboard.reown.com 获取
• metadata.url 与实际域名一致（钱包会验证这一点）
• 从 @reown/appkit/networks 导入网络（不要直接从 viem/wagmi 导入）
• 对于 Next.js：已设置 SSR 标志、实现 Cookie Hydration，并配置 Webpack externals
• 对于 Wagmi：应用已由 WagmiProvider 和 QueryClientProvider 包裹
• Adapter 与目标链匹配（不要将 WagmiAdapter 用于 Solana）
• 在应用初始化时调用一次 createAppKit（不要在组件内部调用）

常见错误

错误	原因	修复方法
"Project ID is required"	缺少 projectId	从 dashboard.reown.com 获取
Hydration 不匹配（Next.js）	缺少 SSR 配置	在 WagmiAdapter 中添加 ssr: true，并使用 cookieToInitialState
模态框未显示	未调用 createAppKit	确保它在应用渲染前运行
网络无法切换	网络导入错误	使用 @reown/appkit/networks，而不是 viem
Webpack 错误（Next.js）	缺少 externals 配置	将 pino-pretty、lokijs、encoding 添加到 webpack externals
Provider 未定义	在连接前访问	使用 Provider 前检查 isConnected

示例

示例 1 — React + Wagmi 基本设置

// config.ts
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
import { mainnet, arbitrum, base } from '@reown/appkit/networks'

export const projectId = 'b56e18d47c72ab683b10814fe9495694' // localhost testing only
export const networks = [mainnet, arbitrum, base]
export const wagmiAdapter = new WagmiAdapter({ networks, projectId })
export const metadata = {
  name: 'My dApp',
  description: 'My dApp description',
  url: 'https://mydapp.com',
  icons: ['https://mydapp.com/icon.png']
}

// App.tsx
import { createAppKit } from '@reown/appkit/react'
import { WagmiProvider } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { projectId, networks, wagmiAdapter, metadata } from './config'

const queryClient = new QueryClient()

createAppKit({
  adapters: [wagmiAdapter],
  networks,
  projectId,
  metadata,
  features: { analytics: true }
})

export default function App() {
  return (
    <WagmiProvider config={wagmiAdapter.wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <appkit-button />
      </QueryClientProvider>
    </WagmiProvider>
  )
}

示例 2 — Vue + Ethers 基本设置

<script lang="ts" setup>
import { createAppKit } from '@reown/appkit/vue'
import { EthersAdapter } from '@reown/appkit-adapter-ethers'
import { mainnet, arbitrum } from '@reown/appkit/networks'

const projectId = 'b56e18d47c72ab683b10814fe9495694' // localhost testing only

createAppKit({
  adapters: [new EthersAdapter()],
  networks: [mainnet, arbitrum],
  projectId,
  metadata: {
    name: 'My Vue dApp',
    description: 'My Vue dApp',
    url: 'https://myapp.com',
    icons: ['https://myapp.com/icon.png']
  }
})
</script>

<template>
  <appkit-button />
</template>

评估

1. 触发场景 — “我想使用 Wagmi 为 React 应用添加钱包连接。如何设置 AppKit？”
2. 非触发场景 — “如何使用 WalletConnect 构建移动钱包？”（使用 WalletKit，而不是 AppKit）
3. 边缘情况 — “我在使用 Next.js，并遇到了 AppKit Hydration 不匹配错误。”（回答：启用 SSR 标志，并使用 cookieToInitialState）
4. 框架选择 — “我有一个 Vue 3 应用，想同时支持 Ethereum 和 Solana。该如何设置？”（回答：Vue + Wagmi + Solana 多链）
5. Adapter 选择 — “我的 React 项目应该使用 Wagmi 还是 Ethers？”（回答：大多数情况下推荐 Wagmi；如果已在使用 ethers.js，则使用 Ethers）
6. 边缘情况 — “我的 AppKit 模态框能显示，但钱包连接失败。”（回答：检查 projectId、metadata.url 域名是否匹配，以及网络配置）