Wagmi Solid 错误类型全解：BaseError 继承体系与 @wagmi/solid 的类型安全错误处理

Wagmi Solid 错误类型全解BaseError 继承体系与 wagmi/solid 的类型安全错误处理【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本文基于wagmi/solid的官方错误 API 文档系统梳理 Solid 适配器导出的全部错误类型以BaseError为根的继承体系、五类核心错误的抛出时机与捕获方式以及 Solid 场景特有的WagmiProviderNotFoundError。结合源码实现你将掌握如何对 Wagmi 错误做instanceof精确判别、读懂错误消息中内嵌的文档链接与版本信息并在 Solid 应用里实现可靠的错误分支处理。错误从哪里来wagmi/solid的错误导出结构wagmi/solid导出的错误类型分两部分Solid 自身定义的错误——BaseError与WagmiProviderNotFoundError定义在 packages/solid/src/errors 目录从wagmi/core再导出的错误——ChainNotConfiguredError、ConnectorNotFoundError等核心错误由 Solid 统一转出使用方无需额外引入wagmi/core。这一结构可以直接从入口导出文件 packages/solid/src/exports/index.ts 中确认Errors 区块先导出 Solid 的BaseError和WagmiProviderNotFoundError随后在wagmi/core区块内把ChainNotConfiguredError、ConnectorAccountNotFoundError、ConnectorAlreadyConnectedError、ConnectorChainMismatchError、ConnectorNotFoundError、ConnectorUnavailableReconnectingError、ProviderNotFoundError、SwitchChainNotSupportedError等类型连同对应的...ErrorType类型一并转出。Base Error所有 Wagmi 错误的公共基类Solid 的 BaseErrorwagmi/solid文档指出所有 Wagmi 错误都继承自BaseError。其源码位于 packages/solid/src/errors/base.tsimport { BaseError as CoreError } from wagmi/core import { getVersion } from ../utils/getVersion.js export type BaseErrorType BaseError { name: WagmiError } export class BaseError extends CoreError { override name WagmiError override get docsBaseUrl() { return https://wagmi.sh/solid // TODO: add solid docs } override get version() { return getVersion() } }可以看到Solid 的BaseError直接继承自wagmi/core的BaseError只做了三处覆写name覆写为WagmiError用于在日志中区分 Solid 层的错误docsBaseUrl覆写为 Solid 文档站点前缀错误消息中内嵌的 Docs 链接会基于此前缀拼装version返回当前wagmi/solid包版本写入错误消息末尾。同时导出的BaseErrorType是交叉类型BaseError { name: WagmiError }——配合 TypeScript 的instanceof收窄可以在 catch 分支获得完整的属性签名。错误消息的拼装规则真正的消息组装逻辑在 packages/core/src/errors/base.ts 的构造函数中。BaseError的构造函数接收一个shortMessage和一个选项对象details或cause二选一另可选docsPath、docsSlug、metaMessages最终message由以下片段用换行符拼接而成this.message [ shortMessage || An error occurred., , ...(options.metaMessages ? [...options.metaMessages, ] : []), ...(docsPath ? [ Docs: ${this.docsBaseUrl}${docsPath}.html${ options.docsSlug ? #${options.docsSlug} : }, ] : []), ...(details ? [Details: ${details}] : []), Version: ${this.version}, ].join(\n)由此得到的属性包括属性说明shortMessage原始简短错误信息如Chain not configured.不含 Docs/Version 后缀message完整消息依次为简短信息、可选 meta 提示、Docs:文档链接、Details:底层细节、Version:包版本details底层错误细节若传入cause会自动取cause.detailscause 本身是 BaseError 时或cause.messagedocsPath该错误对应的文档路径cause是 BaseError 时优先沿用 cause 的 docsPathmetaMessages附加的多行提示如链 ID 对比信息walk(fn)沿cause链向上遍历错误树返回第一个使fn为真的错误便于在嵌套错误中定位特定类型packages/solid/src/errors/context.test.ts 中的内联快照展示了消息的实际形态[WagmiProviderNotFoundError: useConfig must be used within WagmiProvider. Docs: https://wagmi.sh/solid/api/WagmiProvider.html Version: wagmi/solidx.y.z]导入错误类型按 site/solid/api/errors.md 文档所有错误类型都直接从包根导入import { BaseError, ChainNotConfiguredError, ConnectorNotFoundError, // ... } from wagmi/solid利用BaseError做顶层兜底判断即可区分Wagmi 错误与其他运行时异常import { BaseError } from wagmi/solid try { // Wagmi operation } catch (error) { if (error instanceof BaseError) { console.error(Wagmi error:, error.message) console.error(Details:, error.details) } }五类核心错误抛出时机、捕获示例与源码证据ChainNotConfiguredError抛出时机试图使用未在 Wagmi config 中配置的链时抛出。import { ChainNotConfiguredError } from wagmi/solid try { // Operation with unconfigured chain } catch (error) { if (error instanceof ChainNotConfiguredError) { console.error(Chain not configured:, error.message) } }从源码结构看该错误name为ChainNotConfiguredError短消息为Chain not configured.定义在 packages/core/src/errors/config.ts。仓库中至少有三处抛出点packages/core/src/createConfig.tsconfig 中配置了chainId但chains里找不到对应链时if (config.chainId !chain) throw new ChainNotConfiguredError()或getChain无法解析链时packages/core/src/actions/switchChain.tsswitchChain动作无法解析目标链时packages/connectors/src/baseAccount.tsBase Account 连接器解析目标链失败时。这意味着在 Solid 中配置了useSwitchChain或链相关动作后若目标链 ID 不在createConfig的chains数组里就会命中此错误适合引导用户检查 wagmi 配置文件。ConnectorNotFoundError抛出时机试图使用一个不存在或不可用的连接器connector时抛出例如请求一个配置中从未注册的connector.id。import { ConnectorNotFoundError } from wagmi/solid try { // Connect operation } catch (error) { if (error instanceof ConnectorNotFoundError) { console.error(Wallet not installed) } }该错误定义在 packages/core/src/errors/config.ts短消息为Connector not found.。它由connect/disconnect等动作在按 id 查找连接器失败时抛出典型场景是持久化恢复的连接引用了一个当前配置中不存在的连接器。ConnectorAlreadyConnectedError抛出时机试图通过一个已经处于连接状态的连接器再次发起连接时抛出。import { ConnectorAlreadyConnectedError } from wagmi/solid try { // Connect operation } catch (error) { if (error instanceof ConnectorAlreadyConnectedError) { console.error(Already connected) } }抛出点可以直接在 packages/core/src/actions/connect.ts 找到connect动作检测到目标连接器已连接即抛出该错误短消息Connector already connected.同文件位于 packages/core/src/errors/config.ts。在 UI 层捕获它通常意味着无需提示失败可以直接视为已连接并静默忽略。ProviderNotFoundError抛出时机连接器的 provider如注入式钱包的window.ethereum或 SDK 提供的 EIP-1193 provider未找到时抛出。import { ProviderNotFoundError } from wagmi/solid try { // Provider operation } catch (error) { if (error instanceof ProviderNotFoundError) { console.error(Provider not found) } }它是仓库中出现频率最高的一类错误之一packages/core/src/connectors/injected.ts 中有 7 处if (!provider) throw new ProviderNotFoundError()覆盖connect、getProvider、getAccounts、getChainId等操作——当浏览器中不存在注入钱包如 MetaMask 未安装时触发packages/connectors/src/safe.ts 与 packages/connectors/src/walletConnect.ts 的多个操作同样以此错误兜底。因此它是最适合做环境能力探测的错误类型捕获后可以向用户提示请先安装钱包浏览器扩展而不是展示原始堆栈。SwitchChainNotSupportedError抛出时机当前连接器不支持程序化切换链programmatic chain switching时抛出。import { SwitchChainNotSupportedError } from wagmi/solid try { // Switch chain operation } catch (error) { if (error instanceof SwitchChainNotSupportedError) { console.error(Chain switching not supported) } }定义见 packages/core/src/errors/connector.ts构造函数接收{ connector }短消息形如injected does not support programmatic chain switching.其中connector.name会动态插入。抛出点在 packages/core/src/actions/switchChain.ts——当连接器的switchChain方法不存在时抛出。在 Solid 中使用useSwitchChain的 mutation 时onError回调中对该类型的判别可引导用户手动在钱包内切换网络。Solid 特有错误WagmiProviderNotFoundError除再导出的 core 错误外wagmi/solid还定义了 Solid 场景独有的 WagmiProviderNotFoundErrorimport { BaseError } from ./base.js export type WagmiProviderNotFoundErrorType WagmiProviderNotFoundError { name: WagmiProviderNotFoundError } export class WagmiProviderNotFoundError extends BaseError { override name WagmiProviderNotFoundError constructor() { super(useConfig must be used within WagmiProvider., { docsPath: /api/WagmiProvider, }) } }它在 packages/solid/src/primitives/useConfig.ts 中抛出当useConfig在组件树里读不到WagmiContext时说明组件没有被WagmiProvider包裹。这是一个纯配置错误型异常消息固定且附带指向WagmiProviderAPI 文档的 Docs 链接即上文快照所示格式捕获它几乎总意味着需要检查应用根组件的 Provider 装配。完整错误类型一览除本文详述的五类外wagmi/core还导出一组连接器相关错误均已被wagmi/solid统一转出见 packages/solid/src/exports/index.ts 中wagmi/core区块错误类型名称 / 短消息特征抛出场景ChainNotConfiguredErrorChain not configured.使用了 config 中未配置的链ConnectorAccountNotFoundErrorAccount 0x... not found for connector ...指定地址在指定连接器下不存在构造参数为address与connectorConnectorAlreadyConnectedErrorConnector already connected.对已连接连接器重复 connectConnectorChainMismatchError含 Current/Expected Chain ID 对比连接器实际链与连接记录的链 ID 不一致metaMessages会给出两条链 IDConnectorNotConnectedErrorConnector not connected.对未连接连接器执行需要连接的操作ConnectorNotFoundErrorConnector not found.按 id 找不到连接器ConnectorUnavailableReconnectingErrorConnector ... unavailable while reconnecting.重连窗口期内连接器尚未完全恢复details 说明了此时仅id/name/type/uid可用ProviderNotFoundErrorProvider not found.注入/SDK provider 不存在SwitchChainNotSupportedError... does not support programmatic chain switching.连接器未实现程序化切链以上错误的定义集中在 packages/core/src/errors/config.ts 与 packages/core/src/errors/connector.ts。每个错误类都伴随导出一个...ErrorType交叉类型例如ConnectorNotFoundErrorType ConnectorNotFoundError { name: ConnectorNotFoundError }用于在回调参数上做更精确的类型收窄。完整字段说明可参阅 site/core/api/errors.md。实践建议在 Solid 应用中组合使用结合仓库中 site/solid/guides/error-handling.md 的用法错误类型的典型落地位置有两处Query 类原语useBalance等通过返回值的isError/error属性访问error即可能是上述任一BaseError子类Mutation 类原语useConnect、useSwitchChain等在mutate的onError回调里做instanceof判别——import { useConnect, ConnectorNotFoundError } from wagmi/solid function Connect() { const connect useConnect() const handleConnect () { connect.mutate( { connector: injected() }, { onError(error) { if (error instanceof ConnectorNotFoundError) { console.error(Wallet not installed) } else if (error instanceof BaseError) { // 兜底读取 error.details / error.shortMessage console.error(Wagmi error:, error.details) } else { console.error(Unknown error:, error.message) } }, } ) } return ( div button onClick{handleConnect}Connect/button {connect.isError pError: {connect.error?.message}/p} /div ) }判别顺序上先匹配具体错误类、再用BaseError兜底是覆盖Wagmi 错误 / 非 Wagmi 异常两个域的稳妥写法而当错误被更高层包装时可用BaseError的walk方法沿cause链查找特定错误类型避免被外层包装遮蔽。小结wagmi/solid的错误体系可以概括为三点单一基类继承自wagmi/core的BaseErrorname覆写为WagmiError消息自带文档链接与包版本、统一导出Solid 自有错误与 core 错误都从包根转出配合...ErrorType交叉类型支持类型收窄、明确的抛出点config 校验、connect/switchChain 动作、各连接器 provider 缺失兜底。掌握本文列出的各错误类型与其源码位置后你就能在 Solid 应用中把钱包连接、切链等失败路径转化为可预期、可提示的用户体验。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考