Wagmi coinbaseWallet Connector 完整指南从安装配置到 Smart Wallet 参数详解【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi导读coinbaseWallet是 Wagmi 生态中连接 Coinbase Wallet SDK 的标准连接器它让 dApp 能够无缝支持 Coinbase Wallet 浏览器扩展、移动端钱包以及 Coinbase Smart Wallet智能钱包。本文基于当前仓库中 site/shared/connectors/coinbaseWallet.md 文档并结合 packages/connectors/src/coinbaseWallet.ts 源码与测试实现系统讲解该连接器的安装方式、在createConfig中的接入方法、全部配置参数含 Smart Wallet 专属的preference.attribution、keysUrl、options以及底层的工作机制帮助你在 React / Vue / Solid 等框架项目中快速集成 Coinbase Wallet。一、什么是 coinbaseWallet 连接器在 Wagmi 的架构中连接器Connector是连接钱包与dApp之间的桥梁负责执行connect、disconnect、switchChain、getAccounts等底层操作。coinbaseWallet正是官方为 Coinbase Wallet SDK 提供的专用连接器实现位于wagmi/connectors包中。从源码看coinbaseWallet.ts 通过createConnector工厂函数构建连接器其基础元信息为idcoinbaseWalletSDK用于在 Wagmi 内部标识该连接器nameCoinbase Walletrdnscom.coinbase.wallet符合 EIP-1193 的反向域名标识便于生态工具识别测试用例 coinbaseWallet.test.ts 也印证了这一点——对coinbaseWallet({ appName: wagmi })初始化后的连接器其name即为Coinbase Wallet。需要说明的是本文档对应的 API 页面site/core/api/connectors/coinbaseWallet.md、site/react/api/connectors/coinbaseWallet.md、site/vue/api/connectors/coinbaseWallet.md均通过include机制复用同一份共享文档 site/shared/connectors/coinbaseWallet.md因此核心、React、Vue 三套框架的接入方式完全一致只是导入路径略有差异。二、安装添加 coinbase/wallet-sdk 依赖coinbaseWallet连接器本体位于wagmi/connectors包内但底层依赖 Coinbase 官方的coinbase/wallet-sdk。在 packages/connectors/package.json 中coinbase/wallet-sdk被声明为可选 peerDependency版本要求^4.3.6peerDependenciesMeta中标记为optional: true这意味着使用coinbaseWallet时你必须自行安装该依赖否则连接器无法工作。根据文档可通过以下任一包管理器安装# pnpm pnpm add coinbase/wallet-sdk^4.3.6 # npm npm install coinbase/wallet-sdk^4.3.6 # yarn yarn add coinbase/wallet-sdk^4.3.6 # bun bun add coinbase/wallet-sdk^4.3.6版本号请以你安装的wagmi/connectors对应声明的 peerDependency 范围为准当前仓库为^4.3.6。该 SDK 遵循 OSI 兼容的开源许可证可通过 Coinbase 官方仓库查阅具体许可条款。三、快速接入在 createConfig 中启用 coinbaseWallet3.1 导入从wagmi/connectors或框架对应的wagmi/connectors、wagmi/connectors子路径导入import { coinbaseWallet } from wagmi/connectors在 React 项目中导入路径为wagmi/connectors核心Core与 Vue 项目使用wagmi/connectors。该导出由 packages/connectors/src/exports/index.ts 统一对外提供coinbaseWallet函数及其参数类型CoinbaseWalletParameters。3.2 配置示例将连接器放入createConfig的connectors数组中即可import { createConfig, http } from wagmi/core import { mainnet, sepolia } from wagmi/core/chains import { coinbaseWallet } from wagmi/connectors export const config createConfig({ chains: [mainnet, sepolia], connectors: [coinbaseWallet()], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })3.3 生产环境前的必读警告官方文档特别强调在进入生产环境之前强烈建议为你的应用设置appName和appLogoUrl以便在连接钱包时正确展示应用信息。也就是说不要在生产环境直接调用coinbaseWallet()空参数形式至少要传入品牌信息见下文参数详解。3.4 连接器的使用流程配置完成后即可通过 Wagmi 的核心 action 或框架 Hooks 使用该连接器核心connect({ connector })、useConnectors()等ReactuseConnect()、useConnectors()参见 site/react/guides/connect-wallet.md 中的交互示例——渲染useConnectors()返回的连接器列表用户点击后调用connect({ connector })底层连接流程由 coinbaseWallet.ts 的connect方法驱动它通过eth_requestAccounts请求账户、注册accountsChanged/chainChanged/disconnect三个事件监听器、在传入chainId且与当前链不一致时自动执行switchChain最后返回accounts与chainId。如果用户在弹窗中关闭了钱包错误信息匹配user closed modal、user denied account、request rejected等关键词连接器会将其规范化为UserRejectedRequestError抛出。四、参数详解CoinbaseWalletParameterscoinbaseWallet接受的参数类型为CoinbaseWalletParameters其定义见 coinbaseWallet.ts本质上是对coinbase/wallet-sdk中createCoinbaseWalletSDK入参的透传唯一剔除的是appChainIds——因为链列表由 Wagmi 的config.chains统一管理SDK 初始化时会被自动填充为config.chains.map((x) x.id)见 coinbaseWallet.ts。更完整的参数列表请参考 Coinbase Wallet SDK 官方文档。以下为本仓库文档明确收录的关键参数。4.1 appNamestring— 应用名称在钱包连接弹窗与授权界面中展示。import { coinbaseWallet } from wagmi/connectors const connector coinbaseWallet({ appName: My Wagmi App, })4.2 appLogoUrlstring | null | undefined— 应用 Logo 图片 URL。若未指定SDK 会回退使用网站 favicon。const connector coinbaseWallet({ appName: My Wagmi App, appLogoUrl: https://example.com/myLogoUrl.png, })4.3 preference 2.9.0preference用于指定钱包类型偏好自coinbase/wallet-sdk2.9.0 版本起可用。它直接决定了用户连接时看到的是浏览器扩展/移动端钱包还是 Smart Wallet 弹窗。从源码看SDK 初始化时 Wagmi 会以{ options: all, ...(parameters.preference ?? {}) }的形式合并该参数见 coinbaseWallet.ts即默认兜底options: all你传入的偏好会覆盖默认值。const connector coinbaseWallet({ appName: My Wagmi App, preference: { options: smartWalletOnly, }, })preference下还有三个子参数均自 2.12.33 版本起可用4.3.1 attribution 2.12.33类型{ auto?: boolean | undefined; dataSuffix?:0x${string}| undefined }该选项仅适用于 Coinbase Smart Wallet当提供合法的dataSuffix时它会被追加到 Smart Wallet 的initCode与executeBatchcalldata 中Smart Wallet 期望 16 字节的十六进制字符串若dataSuffix不是合法的 16 字节 hex 字符串Smart Wallet 将忽略该属性当auto为true时Smart Wallet 会根据应用来源origin自动生成一个 16 字节的十六进制字符串。const connector coinbaseWallet({ appName: My Wagmi App, preference: { options: smartWalletOnly, attribution: { auto: true, // 或 dataSuffix: 0x 00.repeat(16) }, }, })4.3.2 keysUrl 2.12.33string— 密钥弹窗keys popup的 URL。生产环境默认值为https://keys.coinbase.com/connect开发环境请使用https://keys-dev.coinbase.com/connect。const connector coinbaseWallet({ appName: My Wagmi App, preference: { options: smartWalletOnly, keysUrl: https://keys-dev.coinbase.com/connect, }, })4.3.3 options 2.12.33all | eoaOnly | smartWalletOnly— 要展示的钱包类型偏好三个取值的含义eoaOnly仅使用 EOA 浏览器扩展或移动端 Coinbase WalletsmartWalletOnly仅展示 Smart Wallet 弹窗all默认值根据上下文同时支持eoaOnly与smartWalletOnly。const connector coinbaseWallet({ appName: My Wagmi App, preference: { options: eoaOnly, }, })五、源码视角连接器是如何工作的为了帮助你更透彻地理解配置项背后的行为下面结合 coinbaseWallet.ts 源码拆解几个关键实现细节。5.1 惰性初始化 ProvidergetProvidercoinbaseWallet.ts采用惰性加载策略首次调用时才通过动态import(coinbase/wallet-sdk)创建 SDK 实例并调用sdk.getProvider()获取 EIP-1193 Provider。这种方式让coinbase/wallet-sdk成为真正的可选依赖——即使未安装也不会影响wagmi/connectors包本身的加载只有真正用到coinbaseWallet时才需要该依赖。5.2 链切换与自动添加链switchChaincoinbaseWallet.ts的实现体现了 Wagmi 连接器的标准行为先从config.chains中查找目标链找不到则抛出ChainNotConfiguredError包装为SwitchChainError优先调用wallet_switchEthereumChain请求切换若钱包返回错误码4902表示目标链尚未添加到钱包则自动降级调用wallet_addEthereumChain从 Wagmi 链配置中提取blockExplorerUrls、rpcUrls、chainName、nativeCurrency、iconUrls等组装AddEthereumChainParameter帮助用户一键添加该网络。这意味着只要链已注册在createConfig的chains中用户就能通过 Coinbase Wallet 顺畅切换到该链无需手动在钱包内添加 RPC。5.3 事件监听与状态同步connect成功后连接器会注册三个事件监听器coinbaseWallet.tsaccountsChanged账户变更时通过config.emitter.emit(change, { accounts })同步账户清空时触发断开coinbaseWallet.tschainChanged链切换时发出change事件并携带新的chainIdcoinbaseWallet.tsdisconnect钱包主动断开时发出disconnect事件并统一清理所有监听器coinbaseWallet.ts。disconnect方法coinbaseWallet.ts除了移除监听器外还会调用provider.disconnect()并兼容性地调用可选的provider.close?.()确保钱包端会话真正结束。5.4 connect 的扩展能力connect方法coinbaseWallet.ts额外支持instantOnboarding传入时会在eth_requestAccounts的 params 中携带{ onboarding: instant }实现即时引导流程withCapabilities为true时返回的账户从纯地址数组变为{ address, capabilities: {} }结构为后续 EIP-5792Capabilities等能力协商预留接口源码注释显示未来版本可能将其设为默认行为。六、常见问题与注意事项6.1 依赖缺失如果只安装wagmi/connectors而没有安装coinbase/wallet-sdk调用coinbaseWallet()后初始化 Provider 时会在动态 import 阶段失败并抛出错误。务必先执行第二节中的安装命令。6.2 版本迁移提示若你从 Wagmi v1 迁移而来请注意 API 变更v1 中的CoinbaseWalletConnector从wagmi/core/connectors/coinbaseWallet导入在新版本中已更名为coinbaseWallet从wagmi/connectors导入详见迁移文档 site/shared/migrate-from-v2-to-v3.md 与 site/core/guides/migrate-from-v1-to-v2.md。同时使用coinbaseWallet必须显式安装coinbase/wallet-sdk在 v2→v3 迁移中这是新增的硬性要求。6.3 Smart Wallet 参数版本门槛attribution、keysUrl、options三个子参数依赖coinbase/wallet-sdk 2.12.33而preference本身要求 2.9.0。如果遇到参数不生效请先确认 SDK 版本满足对应门槛。6.4 测试验证仓库中的 coinbaseWallet.test.ts 展示了最小验证方式用config._internal.connectors.setup(coinbaseWallet({ appName: wagmi }))初始化连接器并断言其name为Coinbase Wallet、connect参数支持instantOnboarding。这可以作为你在项目中验证连接器配置是否正确的基础模板。七、总结coinbaseWallet连接器让 Wagmi 应用以极低的成本接入 Coinbase 生态——既支持传统的 EOA 浏览器扩展与移动端钱包也支持新一代 Smart Wallet。接入时只需三步安装coinbase/wallet-sdk可选依赖、从wagmi/connectors导入coinbaseWallet、在createConfig的connectors数组中注册并配置appName/appLogoUrl生产环境必配以及按需设置preference家族参数。底层由 packages/connectors/src/coinbaseWallet.ts 提供的惰性 Provider 初始化、自动链切换含 4902 降级加链与完善的事件同步机制支撑确保连接、切换、断开全流程的健壮性。更多框架级接入示例可参考 site/react/guides/connect-wallet.md 与共享文档 site/shared/connectors/coinbaseWallet.md。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考