企业官网建设流程全解析

wagmi 核心库 @wagmi/core 版本演进全解析：从 3.6 新特性到 v2/v1 迁移指南

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

@wagmi/core是 wagmi 生态中框架无关的 VanillaJS 核心库（项目源码位于 packages/core），负责连接钱包、读写合约、管理链与连接状态等全部底层逻辑，React、Vue、Solid 等框架适配层均基于它构建。本文以 packages/core/CHANGELOG.md 为主线，系统梳理该库从 v3.6.4 回溯至 v1 大版本的每个关键变更、破坏性改动与迁移步骤，并结合源码验证各 Action 的真实实现，帮助你全面理解当前@wagmi/core的能力边界与演进脉络。

阅读指引：如何从 Changelog 读懂 wagmi core

packages/core/CHANGELOG.md共 3785 行，按语义化版本（SemVer）倒序记录了@wagmi/core从0.0.2（2021 年）到3.6.4（当前）的全部变更，其中包版本号位于 packages/core/package.json（"version": "3.6.4"）。阅读时可以抓住三类信息：

• Minor Changes（次要变更）：新增 Action / Hook、新增 connector、新增子路径导出，是能力扩展的"主线"；
• Patch Changes（补丁变更）：修复特定参数取值、竞态条件、类型推断与依赖版本，往往对应真实用户踩坑后的修复，可作为排查问题的参考手册；
• Breaking Changes（破坏性变更）：集中在 v1.0.0、v2.0.0、v3.0.0 以及 Tempo 子模块，升级时必须逐条对照迁移。

一、当前版本 3.6.x 的新特性与关键修复

3.6.4：创世块与 Tempo API 对齐

• 修复getBalance/getTransactionCount在blockNumber: 0n（创世块）时查询错误区块的问题：0n是合法输入，但此前被当作 falsy 处理而回退到blockTag: 'latest'。查看 packages/core/src/actions/getBalance.ts 的实现即可理解此修复的落点——源码正是通过blockNumber !== undefined判断来区分传参分支的。
• Breaking（@wagmi/core/tempo）：移除Actions.zone.getDepositStatus，以对齐当前 Tempo Zone API。需要等待区块导入时改用Actions.zone.waitForTempoBlock；做一次性读取时使用Actions.zone.getZoneInfo并检查tempoBlockNumber字段。

3.6.3 与 3.6.2：索引为 0 的合法输入与依赖兼容

• 修复getTransaction查询在交易index: 0（区块中第一笔交易）时被禁用的问题：与 3.6.4 同类，属于"合法 falsy 值被误判"的典型 Bug，修复后的实现见 packages/core/src/actions/getTransaction.ts。
• 修复 Tempo Zone Action 与 viem 2.55.2 的兼容性。

3.6.1：等待回执不再因 fallback transport 卡死

修复waitForTransactionReceipt在回退交易（reverted）且 revert reason 查询被 fallback transport 阻塞时一直 pending 的问题。实现中使用了withTimeout包裹与 revert 原因查询相关的调用，参见 packages/core/src/actions/waitForTransactionReceipt.ts。

3.6.0：Tempo 代币读数返回Amount对象

Breaking（@wagmi/core/tempo）：为适配 viem 2.54.0，Tempo 的 token balance 与 allowance 读取现在返回Amount对象，返回值结构发生变化，升级时需同步调整消费代码。

二、Tempo 模块：@wagmi/core/tempo 子路径的成长史

Tempo 是 wagmi 通过/tempo子路径提供的一等支持扩展（packages/core/src/exports/tempo.ts 聚合导出Actions命名空间与dangerous_secp256k1、tempoWallet、webAuthn三个 connector），用于对接 Tempo Zone 协议。它的迭代几乎占据了 3.x 的大部分变更：

一个直观的迁移示例（3.4.12，转账语义化）：

- await Actions.wallet.send(config, { - to: '0x...', - token: '0x...', - value: '1.5', - }) + await Actions.wallet.transfer(config, { + amount: '1.5', + to: '0x...', + token: '0x...', + })

- const send = Hooks.wallet.useSend() + const transfer = Hooks.wallet.useTransfer()

三、webAuthn 与 passkey：免密签名能力的演进

webAuthn connector 在 3.x 中经历了多个关键增强：

• 3.3.4：新增凭据快速路径——capabilities.credential已知时可直接传入以跳过 WebAuthn 仪式（ceremony）；
• 3.3.3：webAuthn#connect支持对任意hash签名；
• 3.3.1：修复使用密码管理器浏览器扩展注册 passkey 时的"illegal invocation"错误；
• 3.2.3：修复 access key 查找使用account地址而非accessKey地址的问题，并将chain透传给 viem 的sendTransaction以保留链特定配置；
• 3.2.1：修复 webAuthn connector 未遵循链特定的prepareTransactionRequest阶段的问题。

四、新 Action 的引入时间线（3.x / 2.x）

Changelog 中最有价值的线索之一是各类 Action 的引入节点，这对理解代码库结构（packages/core/src/actions 下每个 Action 一个文件 + 测试文件）很有帮助：

• 3.4.0：新增signTransactionAction（packages/core/src/actions/signTransaction.ts）；
• 3.3.0：新增getBlobBaseFee（packages/core/src/actions/getBlobBaseFee.ts）、writeContractSync（packages/core/src/actions/writeContractSync.ts）与getContractEvents（packages/core/src/actions/getContractEvents.ts）；
• 2.22.0：新增sendTransactionSync与sendCallsSync；
• 2.17.0：EIP-5792 的 Actions & Hooks 转正（sendCalls、getCallsStatus、getCapabilities等，见 packages/core/src/actions/sendCalls.ts），此前 2.16.x 中waitForCallsStatus、account: null等均为实验性特性；
• 2.12.0：新增watchAssetAction；
• 2.11.0：新增deployContractAction（packages/core/src/actions/deployContract.ts）；
• 2.5.0：新增getTransactionConfirmations；
• 2.4.0：新增prepareTransactionRequest；
• 2.3.0：新增getEnsText；
• 2.2.0：新增getBytecode、getStorageAt、getTransactionReceipt、getProof；
• 2.1.0：新增callAction。

以getBalance的源码实现（packages/core/src/actions/getBalance.ts）为例，可以看到所有 Action 的统一范式：接收config与参数 → 通过config.getClient({ chainId })取得 viem client → 用getAction包装 viem 的 action 并调用 → 将结果与链的nativeCurrency元数据合并返回。这也是@wagmi/core作为"viem 之上的薄封装 + 状态管理"的核心设计。

五、Connector 架构变革：v3.0.0 的可选 peer 依赖

v3.0.0（Major）是 3.x 系列最重要的一次架构调整：所有 connector 依赖全部改为可选 peer 依赖。也就是说，要用某个 connector，必须自行安装其对应的依赖包。完整清单（含推荐版本）：

配合 3.5.3 新增的 connector 特定子路径导出与"可选 connector 依赖导入标记为 optional"，使 Turbopack 等打包器能正确解析这些可选依赖。connector 的具体实现可在 packages/connectors/src 下查看（如 packages/connectors/src/baseAccount.ts、packages/connectors/src/walletConnect.ts）。

其他值得注意的 connector 相关变更：

• 2.18.0：新增baseAccountconnector；
• 2.14.0：connector 接口新增rdns属性，用于在createConfig#multiInjectedProviderDiscovery开启时，按 EIP-6963 提供者的rdns去重注入型 provider；2.14.6进一步支持多个rdns条目；
• 2.8.0：connector 新增supportsSimulation属性，标识钱包是否支持合约模拟；
• 2.6.11：弃用normalizeChainId，建议直接用Number。

六、v2.0.0 的重大重构：TanStack Query 与多连接器

v2.0.0 是自 v1 之后最大的一次重构（迁移指南见仓库 site/core/guides/migrate-from-v1-to-v2.md），核心能力包括：

• 完整的 TanStack Query 支持 + queryKeys：@wagmi/core/query子路径（packages/core/src/exports/query.ts）提供与 TanStack Query 深度集成的 query options；
• 同时连接多个 connector；
• 未连接状态下也能切换链；
• EIP-6963 原生支持：浏览器多钱包发现协议；
• 强类型的chainId与 chain 属性；
• 更小的打包体积。

配套的基础设施变更包括：2.3.1 修改持久化策略为"仅存储水合前需要的 critical 属性"；2.6.9 修复 SSR 水合问题；2.6.17 修复使用持久化 store 时活动链未正确 rehydrate 的问题；2.13.3 为持久化的chainId增加状态校验；2.11.4 将Register改为interface以支持声明合并（module augmentation）。

七、事务发送 API 的破坏性演进（v0.5 → v1）

早期版本（0.5.0）引入了prepareSendTransaction/prepareWriteContract前置准备模式：sendTransaction/writeContract只接受"已准备"的配置，或者显式传入mode: 'recklesslyUnprepared'跳过准备。同时：

• sendTransaction返回值收敛为{ hash, wait }，不再返回完整TransactionResponse（需要完整数据用fetchTransaction）；
• 传入chainId时不再自动切换链，而是"用户处于错误链时直接抛错"，避免创建长时间异步任务带来 iOS App Links 等 UX 问题；
• v0.6.0 将合同类 Action 参数统一为单一配置对象，addressOrName→address、contractInterface→abi，args必须为数组，并依赖 TypeScript 4.7.4+ 的extends约束实现基于 ABI 的端到端类型推断（配合as const断言）；
• v0.6.0 同时要求alchemyProvider/infuraProvider必填apiKey（统一取代alchemyId/infuraId），并移除 CommonJS 支持；
• v0.7.0 移除 ropsten、rinkeby、kovan 等废弃测试网链；
• v0.8.0 重构Chain类型：rpcUrls变为{ http: string[]; webSocket: string[] }结构（访问方式从mainnet.rpcUrls.alchemy变为mainnet.rpcUrls.alchemy.http[0]），multicall/ens移入contracts对象（mainnet.contracts.multicall3），waitForTransaction改用hash参数并对 revert / replace / cancel 的交易抛错。

八、Provider 与配置体系：configureChains 到 createConfig

v0.3.0 引入configureChainsAPI，把"为每条链推导 RPC URL、实例化 provider"的逻辑收归一处，connector 不再需要根据chainId手动拼接 RPC URL。v0.4.0 起createClient的provider变为必填；v1.0.0-next 系列则完成了createClient→createConfig、getClient→getConfig的命名迁移，并新增config.setPublicClient、config.setWebSocketPublicClient、config.setConnectors。这些配置能力在今天的 packages/core/src/createConfig.ts 中得到完整保留与扩展。

存储与 SSR 相关修复同样是高频主题：2.1.1 修复含特殊字符（如=）cookie 的 SSR 支持；2.10.5 修复cookieStorage跨路径失效；2.13.2 修复内置 cookie storage 的removeItem在所有路径生效；2.16.1 为默认存储的setItem增加QuotaExceededError、SecurityError等异常处理；3.4.12 处理cookieToInitialState收到畸形 cookie 状态的问题。

九、升级路线与版本对照速查

如果正在规划升级，可按如下主线对照：

1. 从 v1 升级到 v2：对照 site/core/guides/migrate-from-v1-to-v2.md，重点处理 TanStack Query 集成、createConfigAPI、EIP-6963 相关配置；
2. 从 v2 升级到 v3：重点是安装各 connector 的可选 peer 依赖（见第五节表格），并处理 2.x 末期已标记 experimental 的 EIP-5792 API 的转正差异；
3. 使用 Tempo 子路径的应用：额外跟踪/tempo专属的破坏性变更（3.2.0、3.4.10、3.4.12、3.6.0、3.6.4），并保持viem与accountspeer 依赖版本与变更记录一致（当前@wagmi/core的 peer 依赖要求见 packages/core/package.json：viem 2.x、@tanstack/query-core >=5.0.0、accounts ~0.14、typescript >=5.9.3）。

十、进一步阅读

• 核心源码入口：packages/core/src/exports/index.ts，以及按场景拆分的子路径./actions、./query、./codegen、./tempo（子路径声明见 packages/core/package.json）；
• Action 全集与测试：packages/core/src/actions（每个 Action 均配套.test.ts/.test-d.ts）；
• Tempo 扩展实现：packages/core/src/tempo/AGENTS.md、packages/core/src/tempo/Connectors.ts；
• 文档站对应页面：site/core/api/actions.md、site/core/api/createConfig.md 与 site/core/api/errors.md。

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi