wagmi 自定义 Transportcustom接入指南为 Ethereum 应用配置任意 JSON-RPC Provider【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmicustomTransport 允许在 wagmi 中绕过固定 URL 的 RPC 端点直接传入一个符合 EIP-1193 规范的request函数来与任意 JSON-RPC API 通信是实现钱包 Provider 适配、自定义 RPC 网关、测试替身与跨框架复用的关键入口。本文以 site/react/api/transports/custom.md其正文来自共享文档 site/shared/transports/custom.md为核心结合 wagmi 源码与测试完整讲解它的导入方式、配置参数、重试机制与在 React 环境下的实际用法。Transport 在 wagmi 中的地位在 wagmi 中Transport 是连接链与客户端之间的桥梁。createConfig通过transports对象把每个chain.id映射到一个 Transport从而决定该链上的读取、写入与合约调用请求走哪条网络通道export const config createConfig({ chains: [mainnet], connectors: [injected()], transports: { [mainnet.id]: custom({ /* ... */ }), }, })wagmi 原生导出了三类 Transport全部通过viem转发见 packages/core/src/exports/index.ts 的export { custom, http, webSocket } from viemhttp通过固定的 HTTP URL 连接 RPC 端点webSocket通过 WebSocket 连接 RPC 端点custom通过自定义的 EIP-1193request函数连接是本文主题。同时 wagmi 还提供了fallbackpackages/core/src/transports/fallback.ts与unstable_connectorpackages/core/src/transports/connector.ts两个组合型 Transport可与custom组合使用。在 React 包中custom同样从wagmi/core被重新导出见 packages/react/src/exports/index.ts因此 React、Core 用户使用完全一致的 API。导入 custom Transport在所有框架React、Vue、Solid 或纯 Core中custom都可以直接从包顶层导入import { custom } from wagmi对于仅使用 core 的场景则从wagmi/core导入import { custom } from wagmi/core基本用法在 createConfig 中注册自定义 RPC最典型的用法是在createConfig的transports中将某个链的 Transport 指定为custom并传入一个request函数import { createConfig, custom, } from wagmi import { mainnet } from wagmi/chains import { customRpc } from ./rpc export const config createConfig({ chains: [mainnet], connectors: [injected()], transports: { [mainnet.id]: custom({ async request({ method, params }) { const response await customRpc.request(method, params) return response }, }), }, })其中./rpc中的customRpc可以是任意实现了request方法的 JSON-RPC 客户端例如 ethers 的JsonRpcProvider、MetaMask 等注入式钱包的window.ethereum、测试网络的 stub或经过包装的网关客户端。从源码结构看custom本身不负责链的校验、连接管理或地址解析它只负责把{ method, params }转发给你提供的request实现因此它具有极强的通用性。参数详解provider必填{ request({ method: string, params: unknown[] }): Promiseunknown }custom的第一个参数是一个 EIP-1193 规范的request函数。EIP-1193 定义了 Ethereum Provider 的标准接口其核心就是request方法接收一个 JSON-RPC 请求对象method与可选的params返回一个 Promise。任何符合该规范的 Provider注入式钱包、钱包 SDK、本地节点封装等都可以直接传入import { customRpc } from ./rpc const transport custom({ async request({ method, params }) { const response await customRpc.request(method, params) return response }, })key可选stringTransport 的键默认为custom。key在客户端创建时用于标识与查找对应的 Transportconst transport custom( provider, { key: windowProvider, }, )name可选stringTransport 的名称默认为Ethereum Provider。该名称主要用于日志与调试信息展示const transport custom( provider, { name: Window Ethereum Provider, }, )retryCount可选number请求失败时的最大重试次数默认为3。注意该参数是“最大重试次数”即最多额外重试 3 次总共最多发出 4 次请求const transport custom(provider, { retryCount: 5, })retryDelay可选number重试之间的基础延迟毫秒。默认情况下 Transport 会采用指数退避策略计算公式为~~(1 count) * retryDelay意味着重试间隔并非恒定值而是随重试次数指数增长const transport custom(provider, { retryDelay: 100, })结合源码理解Transport 配置如何在链上落地custom在 wagmi 中是一个透明转发自 viem 的 API但理解它如何与 wagmi 的客户端体系协作有助于在实际项目中排错与调优。wagmi 自身实现的两个组合型 Transport 与custom遵循完全一致的配置协议可作为对照参考。以 packages/core/src/transports/connector.ts 中的ConnectorTransportConfig为例它定义了与custom相同的四个可选配置项export type ConnectorTransportConfig { /** The key of the transport. */ key?: TransportConfig[key] | undefined /** The name of the transport. */ name?: TransportConfig[name] | undefined /** The max number of times to retry. */ retryCount?: TransportConfig[retryCount] | undefined /** The base delay (in ms) between retries. */ retryDelay?: TransportConfig[retryDelay] | undefined }其实现unstable_connectorpackages/core/src/transports/connector.ts展示了 Transport 的完整生命周期设置默认值key默认为connector、name默认为Connector当客户端实际发起请求时Transport 函数被调用接收chain与connectors等参数通过connectors.getState().find(...)找到目标连接器调用其getProvider({ chainId })取得 Provider对eth_chainId进行带重试与超时100ms的探测校验当前链与目标链一致不一致则抛出ChainDisconnectedError最终通过createTransport组装出标准 Transport 对象将key、name、retryCount、retryDelay一并下发。可以推断custom传入的request函数最终也会被 viem 的createTransport包装为同样的 Transport 结构并应用相同的重试与超时策略。这意味着你为custom设置的retryCount/retryDelay会作用于其内部的每一次 JSON-RPC 请求因此当你的自定义 Provider 偶发网络抖动时retryCount: 3默认值能提供基本的容错若你的 Provider 对高并发请求敏感可适当增大retryDelay以拉长退避间隔降低瞬时压力若你的 Provider 自身已实现完整重试可将retryCount设为0关闭 wagmi 侧的重试避免双重重试造成请求堆积。常见应用场景1. 适配注入式钱包 / 自定义 Providercustom最常见的用途是把window.ethereum之类的 EIP-1193 Provider 包装为可用的 Transport从而让应用既能使用 wagmi 的 connectors又能直接通过底层 Provider 发起 JSON-RPC 调用。2. 接入非标准 RPC 网关当你的 RPC 端点需要签名、鉴权、限流等自定义逻辑时http无法表达这些行为此时用custom在request内部完成包装即可。3. 测试替身与模拟在单元测试中可以传入一个返回固定响应或按方法分发的 mockrequest函数从而在不依赖真实网络的情况下验证应用逻辑可参考 packages/core/src/transports/fallback.test.ts 与 packages/core/src/transports/connector.test.ts 了解 wagmi 对 Transport 行为的测试方式。4. 与 fallback 组合实现多通道容灾fallbackTransport 接受一组 Transport 并依次尝试因此可以把custom与http、webSocket组合形成“自定义通道优先、公共 RPC 兜底”的策略import { createConfig, custom, fallback, http } from wagmi import { mainnet } from wagmi/chains export const config createConfig({ chains: [mainnet], transports: { [mainnet.id]: fallback([ custom({ /* 自定义网关 */ }), http(https://cloudflare-eth.com), ]), }, })相关参考Transport 参考文档site/shared/transports/custom.md、site/react/api/transports/custom.md、site/react/api/transports/http.mdCore 源码导出packages/core/src/exports/index.tsReact 源码导出packages/react/src/exports/index.ts组合型 Transport 实现packages/core/src/transports/fallback.ts、packages/core/src/transports/connector.ts链与 Transport 配置示例playgrounds/vite-react/wagmi.config.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考