wagmi unstable_connector Transport通过 Connector 的 EIP-1193 Provider 路由 JSON-RPC 请求【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiunstable_connector是 wagmi 提供的一种 Transport它将 JSON-RPC 请求转发到createConfig中已注册的某个 Connector 所持有的 EIP-1193 Provider 上。例如当 Connector 为injected且用户安装了 MetaMask 时所有出站 RPC 请求都会经由 MetaMask 注入的 Providerwindow.ethereum发出而不是走中心化节点。读完后你将掌握该 Transport 的导入与配置方式、全部参数connector、key、name、retryCount、retryDelay的默认值以及从源码层面理解它的请求链路、重试/超时策略与链 ID 校验机制。角色定位Connector 作为 RPC 通道wagmi 的createConfig通过transports配置决定每条链的 JSON-RPC 请求走哪个通道http、webSocket、custom或这里介绍的unstable_connector见 导出入口其中custom、http、webSocket直接复用 viem 的实现unstable_connector与fallback则定义在 wagmi 核心包内。unstable_connector的特殊之处在于它把钱包本身变成 RPC 通道。以injectedConnector 为例其getProvider实现会在浏览器环境下从window.ethereum或targetMap中定义的其他注入目标取出 Provider见 injected.ts。当用户已连接钱包时链上数据读取可以直接通过钱包代理发出天然拥有已授权账户的上下文。导入与基本用法导入方式wagmi为根包wagmi/core、wagmireact、wagmi/vue等各框架包均有导出例如 React 包导出import { unstable_connector } from wagmi文档给出的标准用法——配合createConfig、fallback与http使用原样继承自 官方文档import { createConfig, fallback, unstable_connector, // [!code hl] } from wagmi import { mainnet } from wagmi/chains export const config createConfig({ chains: [mainnet], connectors: [injected()], transports: { [mainnet.id]: fallback([ unstable_connector(injected), // [!code hl] http(https://foo-bar-baz.quiknode.pro/...) ]) }, })这里有一个从源码可见的关键细节unstable_connector接收的参数类型是PickConnector, type见 connector.ts它只读取传入对象的type字段——上例中传入的是injected这个工厂函数其静态属性type为injected见 injected.ts 第 37 行而不是你在connectors数组里injected()创建出来的实例。Transport 在运行时会根据这个type从createConfig传入的 connectors store 中反查真正注册的 Connector 实例因此你在connectors: [injected()]中为injected配置的target、shimDisconnect等参数依然会生效。参数说明unstable_connector的第二个参数为ConnectorTransportConfig定义于 connector.ts 第 17–26 行connector必填ConnectorTransport 所依赖的 Connector。传入的对象只需携带正确的type标识Transport 会在运行时按type从 config 中查找对应实例import { unstable_connector } from wagmi import { safe } from wagmi/connectors const transport unstable_connector(safe) // [!code focus]key可选stringTransport 的 key默认为connectorimport { unstable_connector } from wagmi import { injected } from wagmi/connectors const transport unstable_connector(injected, { key: injected, // [!code focus] })name可选stringTransport 的名称默认为Connectorimport { unstable_connector } from wagmi import { injected } from wagmi/connectors const transport unstable_connector(injected, { name: Injected, // [!code focus] })retryCount可选number请求失败时的最大重试次数默认3。从源码看这里有一个优先级逻辑config.retryCount ?? parameters.retryCountconnector.ts 第 39 行即未显式传入时回退到createConfig层面的默认值。测试快照印证了默认值retryCount: 3connector.test.ts。import { unstable_connector } from wagmi import { injected } from wagmi/connectors const transport unstable_connector(injected, { retryCount: 5, // [!code focus] })retryDelay可选number两次重试之间的基础延迟毫秒。默认情况下 Transport 使用指数退避策略~~(1 count) * retryDelay即重试间隔并非常数。测试快照显示未显式传入时retryDelay取150即首次重试基础延迟 150ms。import { unstable_connector } from wagmi import { injected } from wagmi/connectors const transport unstable_connector(injected, { retryDelay: 100, // [!code focus] })为什么强烈建议包裹在 fallback 中官方文档给出了明确的警告建议把unstable_connector放在fallbackTransport 内使用确保 Connector 请求失败时能回退到 fallback 集合中的其他 Transport如http节点。文档列举了 Connector 请求失败的常见情形链 ID 不匹配钱包当前链与请求目标链不一致Connector 的 RPC 不支持请求的方法或仅对已连接账户支持部分方法Connector 的 RPC 被限流。fallback在 wagmi 中是 viemfallback的薄封装依次尝试列表中的 Transport见 fallback.ts。上面用法示例中「unstable_connector在前、http在后」正是利用这一点优先享受钱包通道的便利失败后无缝落到公共节点避免请求彻底中断。源码解析一次请求的完整生命周期unstable_connector的核心实现只有几十行connector.ts其request函数第 41–76 行执行以下流程按 type 查找 Connector从parameters.connectorsconfig 持有的 store中查找type匹配的实例。找不到时抛出ProviderDisconnectedError错误详情为Could not find connector of type ... in \connectors passed to createConfig.——这也解释了为什么connectors 配置里必须注册与被引用同类型的 Connector。获取 Provider调用connector.getProvider({ chainId: chain?.id })。若返回undefined例如在 SSR/Node 环境下window不存在injected的getProvider会直接返回undefined抛出ProviderDisconnectedErrorProvider is disconnected.。预检eth_chainId对eth_chainId请求应用了withRetrywithTimeout超时固定 100ms的组合策略——源码注释说明原因是部分注入式钱包如 MetaMask在页面加载初期无法立即解析 JSON-RPC 请求connector.ts 第 58–66 行。拿到链 ID 后与目标chain.id比对不一致则抛出ChainDisconnectedError错误信息会同时给出当前链 ID 与目标链 ID/名称这正是文档中「Chain ID mismatches」这一失败场景的底层实现。转发业务请求预检通过后将{ method, params }原样交给provider.request。最后通过 viem 的createTransport组装出type: connector的 Transport 对象并传入key、name、retryCount、retryDelay配置第 78–85 行。测试用例验证的错误语义connector.test.ts 用四个行为用例覆盖了上述每条失败路径可作为排错时对照的错误签名场景结果传入未注册的 type{ type: foo }拒绝并抛出ProviderDisconnectedError: ... Could not find connector of type foo in \connectors...第 31–41 行getProvider返回undefined抛出ProviderDisconnectedError: ... Provider is disconnected.第 43–63 行钱包当前链与目标链不符mock 钱包在链 1目标 Optimism 链 10抛出ChainDisconnectedError: ... The current chain of the connector (id: 1) does not match the target chain ... (id: 10 – OP Mainnet).第 65–87 行正常路径transport.request({ method: eth_chainId })成功解析为0x1第 89–97 行这些用例同时验证了一个实现事实Transport 的request失败时抛出的是 viem 标准错误类型因此在fallback中能被正常识别并触发降级——用户无需为这类失败编写特殊处理。适用边界与注意事项命名中的unstable前缀函数名带unstable_表示该 API 仍处于实验阶段行为可能在后续版本中调整使用前建议确认当前仓库/版本中的签名当前实现以packages/core/src/transports/connector.ts为准。SSR 场景由于injected等浏览器 Connector 在window不存在时取不到 Provider服务端渲染阶段该 Transport 必然抛出ProviderDisconnectedError这正是官方强烈建议用fallback兜底的另一个原因。方法支持面钱包代理的 RPC 能力受钱包实现约束部分方法仅对已连接账户可用对方法覆盖面要求高的操作建议将公共节点作为 fallback 或主通道。相关导出类型ConnectorTransport与ConnectorTransportConfig与unstable_connector一同从 packages/core/src/exports/index.ts 导出供需要精确类型标注的项目使用。参考文件实现packages/core/src/transports/connector.ts测试packages/core/src/transports/connector.test.tsfallback 封装packages/core/src/transports/fallback.tsinjected Connector 实现packages/core/src/connectors/injected.ts官方文档core / react / vue 共享site/shared/transports/unstable_connector.md、site/core/api/transports/unstable_connector.md【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考