Wagmi Vue 快速上手指南从安装到第一个响应式以太坊组合式函数【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiWagmi 是一套面向 Vue 的以太坊响应式组合式函数Composition Utilities集合本指南带你从零开始把wagmi/vue集成进 Vue 3 应用既可以用官方 CLI 一键脚手架也可以手动安装viem与tanstack/vue-query精确控制依赖。读完本文你将掌握完整的接入链路——创建并注册 Config、挂载WagmiPlugin与VueQueryPlugin以及使用useConnection、useEnsName等组合式函数读写链上数据并通过 TypeScript 注册机制获得链级类型安全。OverviewWagmi 是什么Wagmi 是 wagmi谐音 wag me即 wager me的缩写项目描述为 Reactive primitives for Ethereum apps。作为 Vue 的以太坊组合式函数集合它把钱包连接、链上读写、合约交互、ENS 解析等能力封装成一个个响应式 composable让开发者以声明式的方式编写 dApp。想了解项目背后的设计动机可阅读 Why Wagmi 一节。Wagmi 的核心设计分为三层从 packages/vue/src/exports/index.ts 的导出结构可以清晰看到wagmi/core框架无关的核心层提供createConfig、createConnector、getConnection、http/custom/webSocket传输层等底层能力被 Vue 包整体 re-exportwagmi/vue组合式函数层约 30 个useXxx组合式函数useBalance、useBlockNumber、useReadContract、useWriteContract、useSignMessage、useWatchContractEvent等见 packages/vue/src/composablesTanStack Query 层所有查询类 composable 都基于 TanStack Query 的异步状态管理自动获得缓存、去重、重试与失效能力。自动安装使用 create-wagmi CLI 脚手架对于全新项目官方推荐使用create-wagmi命令行工具完成初始化。它会自动创建基于 TypeScript 的 Wagmi 项目并安装所需依赖支持四种包管理器# pnpm pnpm create wagmi # npm npm create wagmilatest # yarn yarn create wagmi # bun bun create wagmi命令执行后会出现一组交互式提示Project name: wagmi-project Select a framework: Vue / Vanilla ...从 packages/create-wagmi/src/cli.ts 的源码可以看到 CLI 的完整交互流程先询问项目名默认wagmi-project若目标目录非空会确认是否覆盖随后校验包名合法性再询问选择框架Vue 与 Vanilla 均为可用选项。CLI 还支持--template、--pnpm、--npm、--yarn、--bun等选项以跳过部分交互。提示完成后CLI 会在当前目录下创建以项目名命名的目录并安装依赖。脚手架生成的项目结构可参考 packages/create-wagmi/templates/vite-vue 与 packages/create-wagmi/templates/vite-vanilla创建后请查看项目内的README.md获取后续指引。手动安装精确定制你的依赖如果要在现有 Vue 3 项目中集成 Wagmi需要手动安装三个包# pnpm pnpm add wagmi/vue viem2.x tanstack/vue-query # npm npm install wagmi/vue viem2.x tanstack/vue-query # yarn yarn add wagmi/vue viem2.x tanstack/vue-query # bun bun add wagmi/vue viem2.x tanstack/vue-query本文仓库中viem的版本要求以packages/vue/package.json中的peerDependencies为准viem: 2.x安装时请使用与你项目匹配的 2.x 版本。三个依赖各司其职ViemTypeScript 优先的以太坊接口层负责实际与区块链交互RPC 请求、交易构造、ABI 编解码等。Wagmi 的传输层http、webSocket与链定义mainnet、sepolia等均来自 Viem**TanStack Query 的 peerDependenciesTypeScript可选但强烈推荐。Wagmi 的类型系统能根据 Config 推导链 ID 与合约 ABI 类型详见 TypeScript 支持文档。此外需要注意 peerDependencies 中还声明了vue 3Wagmi 面向 Vue 3 的组合式 API 设计无法在 Vue 2 中使用。创建 Config定义链与传输层安装完成后第一步是使用createConfig创建并导出一个 Wagmi 配置对象。完整的可运行示例见 site/snippets/vue/config.tsimport { createConfig, http } from wagmi/vue import { mainnet, sepolia } from wagmi/vue/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })这段配置声明了两件事chains应用支持的链列表这里配置了以太坊主网Mainnet与 Sepolia 测试网。链定义从wagmi/vue/chains子路径导入该导出在 packages/vue/package.json 的 exports 中有明确声明transports每条链对应的 JSON-RPC 传输层。http()表示使用公开/默认 RPC 端点你也可以传入自定义 RPC URL如http(https://rpc.example.com)或使用webSocket()、fallback()、custom()等传输方式。createConfig的完整配置项包括connectors、storage、ssr等可查阅 createConfig 文档。值得强调的是Config 是 Wagmi 一切能力的源头它持有链、传输层、连接器与存储状态wagmi/core中的createConfig实现还负责维护存储序列化与多连接管理相关状态类型见 packages/core/src/types。TypeScript 提示注册 Config 获得链级类型安全Wagmi 的类型系统允许你通过两种方式把 Config 的链信息注入类型环境让chainId等参数被严格限定在已配置的链范围内import { type Config } from wagmi/vue import { mainnet, sepolia } from wagmi/vue/chains declare const config: Configreadonly [typeof mainnet, typeof sepolia] // 方式一注册 Config模块增强 import { useBlockNumber } from wagmi/vue useBlockNumber({ chainId: 123 }) // ❌ 类型错误123 不在 Mainnet/Sepolia 中 declare module wagmi/vue { interface Register { config: typeof config } }// 方式二使用 hook 的 config 参数显式传入 import { useBlockNumber } from wagmi/vue useBlockNumber({ chainId: 123, config }) // ❌ 同样被类型系统拦截采用注册或显式传config后useBlockNumber的chainId会被强类型约束为只允许主网与 Sepolia 的链 ID1与11155111。这与 packages/vue/src/composables/useConfig.ts 的实现相呼应——该 composable 支持两种取值路径显式传入parameters.config时直接透传否则从 Vue 的注入上下文Injection Context中取。更深入的类型用法见 TypeScript 文档的 Config Types 一节。添加 WagmiPlugin把 Config 注入应用Config 创建好后需要把它挂到 Vue 应用实例上这通过WagmiPlugin完成packages/vue/src/plugin.ts// main.ts import { WagmiPlugin } from wagmi/vue // [!code focus] import { createApp } from vue import { config } from ./config // [!code focus] import App from ./App.vue createApp(App) .use(WagmiPlugin, { config }) // [!code focus] .mount(#app)从 plugin.ts 的源码可以看到插件的内部机制插件通过app.provide(configKey, config)把 Config 以 Symbol key 注入应用上下文这正是useConfig里inject(configKey)能取到 Config 的原因WagmiPluginOptions还支持两个可选参数initialStateSSR 场景下从服务端序列化传入的初始状态配合wagmi/core的hydrate使用相关工具见 packages/core/src/hydrate.tsreconnectOnMount默认true应用挂载时自动尝试重新连接上次已连接的连接器Connector插件内部调用wagmi/core的hydrate(config, options)并在onMount时执行重连逻辑。源码注释中也标注了 SSR 环境下的重连与状态水合仍有待进一步验证见 plugin.ts。插件完整 API 详见 WagmiPlugin 文档。设置 TanStack Query接入异步状态管理在WagmiPlugin之后还需要把 TanStack Query 的 Vue 插件挂载到应用上// main.ts import { QueryClient, VueQueryPlugin } from tanstack/vue-query // [!code focus] import { WagmiPlugin } from wagmi/vue import { createApp } from vue import { config } from ./config import App from ./App.vue const queryClient new QueryClient() // [!code focus] createApp(App) .use(WagmiPlugin, { config }) .use(VueQueryPlugin, { queryClient }) // [!code focus] .mount(#app)QueryClient是 TanStack Query 的中央缓存与请求调度器。Wagmi 内部在 packages/vue/src/utils/query.ts 对 TanStack 的useQuery做了薄封装所有查询选项被包进computed以保持响应式同时注入queryKeyHashFn: hashFn来自wagmi/core/query来统一查询键的哈希策略保证 Wagmi 各查询之间的缓存键一致、避免重复请求。有关 TanStack Query 的库级 API 与用法参见 TanStack Query 官方文档。使用 Wagmi组合式函数实战一切就绪后应用内的任意组件都可以使用 Wagmi 的 Vue Composables。以官方示例的完整形态见 site/snippets/vue/config.ts 与下方组件代码为例!-- App.vue -- script setup langts import { useConnection, useEnsName } from wagmi/vue const { address } useConnection() const { data, error, status } useEnsName({ address }) /script template div v-ifstatus pendingLoading ENS name/div div v-else-ifstatus error Error fetching ENS name: {{error.message}} /div div v-elseENS name: {{data}}/div /template// main.ts import { QueryClient, VueQueryPlugin } from tanstack/vue-query import { WagmiPlugin } from wagmi/vue import { createApp } from vue import { config } from ./config import App from ./App.vue const queryClient new QueryClient() createApp(App) .use(WagmiPlugin, { config }) .use(VueQueryPlugin, { queryClient }) .mount(#app)这个例子展示了 Wagmi Vue 组合式函数的两类核心形态1. 响应式状态类 composable——useConnectionpackages/vue/src/composables/useConnection.ts 的实现体现了 Wagmi 的响应式设计通过useConfig(parameters)获取 Config显式传入或从注入上下文获取用 Vue 的reactive()包装getConnection(config)的返回值得到响应式连接状态通过watchConnection订阅连接变化onChange回调中用updateState更新响应式对象返回toRefs(readonly(connection))即解包后的一批只读 ref如address、chainId、connector、status因此可以直接在模板与watch中使用同时保证外部无法意外修改内部状态在onScopeDispose中自动取消订阅避免组件卸载后的内存泄漏。2. 查询类 composable——useEnsNamepackages/vue/src/composables/useEnsName.ts 是查询类 composable 的典型实现它把getEnsNameQueryOptions计算为computed默认chainId取自useChainId()即当前激活链最终交给上文的useQuery封装执行。因此返回值{ data, error, status }完全遵循 TanStack Query 的状态机pending请求中、error失败含error.message、success成功data为 ENS 名称字符串。注意示例中useConnection()解构出的address是 ref 类型而useEnsName的参数支持DeepMaybeRef自动 unref因此可以直接把addressref 传给它这正是 Wagmi Vue 组合式函数对响应式参数的原生支持。下一步深入 Wagmi Vue 生态完成基础接入后推荐继续探索以下主题TypeScript充分利用 Wagmi 的类型安全与自动推导获得开箱即用的开发体验连接钱包指南让用户连接/断开钱包并展示已连接账户的信息Vue Composables API 总览浏览全部组合式函数useBalance、useReadContract、useWriteContract、useWatchContractEvent、useSignMessage等完整清单见 packages/vue/src/exports/index.ts及各自的参数与返回值Viem 指南理解 Viem 与 Wagmi 如何协作掌握getClient、getConnectorClient等底层访问方式。如果你是 Nuxt 用户wagmi/vue还提供了独立的 Nuxt 模块导出wagmi/vue/nuxt见 packages/vue/src/nuxt可参考 Nuxt 集成文档 获取 SSR 场景下的配置方式。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考