Wagmi CLI 快速上手：从安装配置到 ABI 管理与 React Hooks 代码生成

Wagmi CLI 快速上手从安装配置到 ABI 管理与 React Hooks 代码生成【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiWagmi CLI 是 wagmi 生态中用于管理以太坊合约 ABI 与生成代码的命令行工具它可以自动从 Etherscan 等区块浏览器、Foundry/Hardhat 等项目解析 ABI并为这些 ABI 生成类型安全的 React Hooks 等代码。本文以 site/cli/getting-started.md 为骨架结合仓库内packages/cli的真实源码与测试带你走完安装、初始化配置、添加合约与插件、运行代码生成、使用生成代码的完整流程读完即可在自己的 wagmi 项目中落地 CLI 工作流。Wagmi CLI 能做什么Wagmi CLI 是一个专门面向以太坊开发者的命令行界面其核心价值在于把大量重复劳动自动化从区块浏览器如 Etherscan或本地区块链开发框架如 Foundry、Hardhat获取并管理 ABI再基于这些 ABI 生成诸如 React Hooks 之类的类型安全代码。它的出发点与设计理念可参见仓库中的 Why Wagmi CLI 一节。从packages/cli/package.json可以看到wagmi/cli的定位是 “Manage and generate code from Ethereum ABIs”当前版本为 2.10.0通过bin.wagmi暴露wagmi命令入口为dist/esm/cli.js并以type: module的 ESM 形式发布。这意味着无论使用哪个包管理器最终获得的能力都是同一套 CLI 命令与可编程 API。安装 Wagmi CLIWagmi CLI 通常作为项目的开发依赖安装因为它是构建期/开发期工具生成的代码会提交或由构建流程产出。以下四种包管理器任选其一pnpm add -D wagmi/clinpm install --save-dev wagmi/cliyarn add -D wagmi/clibun add -D wagmi/cli安装完成后即可在项目中通过pnpm wagmi、npx wagmi、yarn wagmi或bun wagmi调用 CLI。仓库中的packages/cli/package.json将typescript声明为可选 peerDependency5.9.3即 TypeScript 不是强制依赖但在生成 TypeScript 输出或使用.ts配置文件时推荐安装。创建配置文件wagmi initCLI 的使用以配置文件为中心。运行init命令即可生成一份初始配置pnpm wagmi initnpx wagmi inityarn wagmi initbun wagmi initinit命令的行为在 init 命令源码 中有清晰体现其决策逻辑值得展开检测已有配置通过findConfig向上层目录查找配置文件。若已存在配置命令会直接提示 “Config already exists at ... 并退出避免覆盖已有配置。判断是否使用 TypeScript调用getIsUsingTypeScript()见 getIsUsingTypeScript.ts其判定方式是向上查找tsconfig.json、tsconfig.base.json、tsconfig.lib.json、tsconfig.node.json或查找wagmi.config.ts、wagmi.config.mts。只要命中其一即视为 TypeScript 项目。决定文件名与内容TypeScript 项目生成wagmi.config.ts否则生成wagmi.config.js。你也可以用--config path显式指定配置文件名此时init会按指定路径写入。写入模板TypeScript 版本使用import { defineConfig } from wagmi/cliexport default defineConfig(...)JavaScript 版本则生成带// ts-check与type {import(wagmi/cli).Config}JSDoc 注解的 ESM 配置文件写入前会经过 Prettier 格式化。生成的配置文件内容大致如下import { defineConfig } from wagmi/cli export default defineConfig({ out: src/generated.ts, contracts: [], plugins: [], })注意init与generate命令都支持-c, --config path与-r, --root path两个选项见 cli.ts 命令定义前者指定配置文件路径后者指定解析配置的根目录。理解配置文件结构init生成的空模板包含三个字段它们正是 Config 类型定义 中的全部配置项配置项类型说明outstring生成代码的输出文件路径必填contractsContractConfig[]直接声明的合约列表名称、ABI、地址pluginsPlugin[]启用的插件列表Etherscan、Foundry、React 等defineConfig是一个纯类型辅助函数其签名接受单个配置对象、配置对象数组或返回配置数组的函数。defaultConfig默认值为{ out: src/generated.ts, contracts: [], plugins: [] }。每个ContractConfig包含三个字段name合约名称用于生成标识符如erc20会派生出erc20Abi、useReadErc20等。abi合约 ABI。address可选单个地址字符串或多链地址对象{ [chainId]: address }。多链对象在生成代码时会附带地址文档注释并额外导出${name}Address与${name}Config常量。如果使用 JavaScript 配置且想获得编辑器的类型提示可以借助 JSDoc 或defineConfig详见 Configuring CLI。配置还可以导出函数支持条件配置与异步配置例如按NODE_ENV返回不同配置或通过loadEnv手动加载.env文件CLI 默认不自动加载.env因为需要先求值配置才能确定加载哪些文件。关于配置文件的查找findConfig.ts 给出了明确的优先级顺序wagmi.config.ts→wagmi.config.js→wagmi.config.mjs→wagmi.config.mts并使用escalade从当前目录向父目录逐层搜索。添加合约与插件配置就绪后就可以向contracts与plugins中添加内容了。下面的示例同时演示了三种典型用法直接引用 viem 提供的erc20Abi、通过etherscan插件按链 ID 拉取链上合约 ABI、通过react插件生成 React Hooks。import { defineConfig } from wagmi/cli import { etherscan, react } from wagmi/cli/plugins import { erc20Abi } from viem import { mainnet, sepolia } from wagmi/chains export default defineConfig({ out: src/generated.ts, contracts: [ { name: erc20, abi: erc20Abi, }, ], plugins: [ etherscan({ apiKey: process.env.ETHERSCAN_API_KEY!, chainId: mainnet.id, contracts: [ { name: EnsRegistry, address: { [mainnet.id]: 0x314159265dd8dbb310642f98f50c066173c1259b, [sepolia.id]: 0x112234455c3a32fd11230c42e7bccd4a84e02010, }, }, ], }), react(), ], })直接声明合约上例中contracts数组里的erc20合约直接复用了 viem 导出的erc20Abi无需网络请求。这是最快的接入方式适合在项目中内联使用常见标准合约 ABI。Etherscan 插件按链拉取 ABIetherscan插件的完整配置项定义在 etherscan.ts 中包括apiKey必填Etherscan API 密钥。chainId必填用于拉取 ABI 的链 ID当address是多链对象时以此选择具体地址。contracts必填待拉取 ABI 的合约列表无需abi字段。cacheDuration可选ABI 缓存时长默认1_800_000毫秒30 分钟。缓存逻辑由 fetch.ts 中的通用fetch助手承担缓存键为etherscan:address或序列化后的多链地址对象。tryFetchProxyImplementation可选是否尝试获取代理合约的实现地址默认false开启后会先调用getsourcecode动作。拉取到的 ABI 会被序列化进生成的out文件因此运行一次generate后即使离线也可以继续使用这些 ABI。React 插件生成 Hooksreact()插件不依赖任何网络请求它纯粹基于已解析的合约来自配置contracts与其它插件的产出生成 React Hooks。从 react.ts 插件实现 可以看到其核心逻辑遍历每个合约的 ABI按函数/事件类型分组然后为每种能力生成对应的 Hooks只读函数view/pure→useRead${Contract}${Item}底层调用createUseReadContract。写入函数nonpayable/payable→useWrite${Contract}${Item}createUseWriteContract与useSimulate${Contract}${Item}createUseSimulateContract。事件→useWatch${Contract}${Item}EventcreateUseWatchContractEvent。默认的命名模式为use${type}${ContractName}${ItemName}watch 额外追加Event例如合约erc20的balanceOf读函数会生成useReadErc20BalanceOf。若同时存在合约级 Hook 与函数级 Hook 时重载函数只生成一个 Hook 以避免冲突。你也可以通过react({ getHookName: ... })自定义命名函数或通过abiItemHooks: false关闭逐函数 Hook 的生成。所有生成的 Hook 都带有基于合约地址的文档注释方便 IDE 悬浮提示。运行代码生成wagmi generate配置完成后执行generate命令即可解析所有 ABI 并将生成代码写入out指向的文件pnpm wagmi generatenpx wagmi generateyarn wagmi generatebun wagmi generate以上示例配置执行generate时命令实际会依次完成以下工作对应 generate.ts 主流程校验etherscan与react两个插件的配置调用每个插件的validate钩子。收集插件提供的合约从 Etherscan 拉取并缓存 ENS Registry 的 ABI按 Mainnet/Sepolia 地址区分。将配置中的erc20Abi以名称ERC20纳入合约集合并按名称排序去重若合约名重复会直接报错。依次运行每个插件的run钩子react插件基于全部合约生成 React Hooks产出以imports、prepend、content三段式拼装。将 ABI 常量、ENS Registry 的多链地址常量、合约配置常量以及所有 React Hooks 写入out文件见writeContracts写入前会自动创建输出目录并格式化。generate命令支持的选项与 generate 命令文档 一致选项类型说明-c, --config pathstring指定配置文件路径-r, --root pathstring解析配置的根目录-w, --watchboolean监听文件变化仅对支持 watch 的插件生效-h, --help-显示帮助信息--watch模式是日常开发的利器对于支持 watch 的插件如 Foundry、Hardhatgenerate --watch会通过 chokidar 监听源码文件变化在文件新增/变更/删除时自动更新对应合约并防抖100ms重写输出文件同时它还会监听配置文件本身的变更并提示重启进程。仓库中 generate.test.ts 覆盖了大量行为验证包括无效 CLI 选项、配置文件缺失、out与合约名重复、ABI/地址非法、未配置合约时的提示以及无 watch 插件时使用--watch的告警等。使用生成的代码generate完成后out如src/generated.ts中会导出所有合约的 ABI 常量、地址常量与 React Hooks。在 React 应用中可以直接导入使用import { useReadErc20, useReadErc20BalanceOf } from ./generated // 使用生成的 ERC-20 合约级读 Hook const { data } useReadErc20({ address: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48, functionName: balanceOf, args: [0xA0Cf798816D4b9b9866b5330EEa46a18382f251e], }) // 使用生成的 ERC-20 balanceOf 专属 Hook函数名已内联 const { data } useReadErc20BalanceOf({ address: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48, args: [0xA0Cf798816D4b9b9866b5330EEa46a18382f251e], })两种写法各有适用场景合约级 Hook如useReadErc20需要在调用时手动指定functionName灵活度更高函数级 Hook如useReadErc20BalanceOf已把函数名固化在类型与实现中参数列表更简洁、类型约束更严格。二者都基于wagmi/codegen中的createUseReadContract等工厂函数因此与 React 组件、TanStack Query 的集成方式与手写 Hook 完全一致。需要留意的是生成的 Hooks 参数中地址与参数类型都源自 ABI 的类型推导通过 abitype 完成错误参数会在编译期被拦截这是使用 CLI 生成代码相比手写裸调用最大的收益之一。关于 out 文件的工程实践官方建议见原文档 tip不要把out文件提交进版本库更稳妥的做法是将其加入.gitignore然后在构建流程或启动开发服务器前触发generate。例如在package.json中添加predev: wagmi generate脚本或在 CI 构建阶段先执行生成步骤保证仓库中始终只保留配置与源码生成的代码随构建即时产出。进阶方向完成上述流程后可以按需深入以下主题Configuring CLI掌握defineConfig的类型提示、条件配置、异步配置、数组配置与环境变量加载等进阶用法。Commands查阅全部 CLI 命令含 generate 与 init的完整选项说明。Plugins浏览插件全集包括 etherscan、react、foundry、hardhat、sourcify、blockExplorer、fetch、actions 等均可通过wagmi/cli/plugins子路径导入。Migrate from v1 to v2如果你是旧版本用户可参照此指南平滑迁移。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考