区块链前端认证鉴权【免费下载链接】web3modalThe full stack toolkit to build onchain app UX项目地址https://gitcode.com/gh_mirrors/we/web3modal点击查看免费下载导读本篇文章以 packages/cli/CHANGELOG.md 为主线系统梳理 Reown AppKit CLIreown/appkit-cli从 1.6.0 到 1.8.24 的版本演进脉络。你将从中掌握CLI 脚手架的完整用法与底层实现基于tiged的模板克隆、Headless 无头模式的程序化连接 API、多链适配EVM / Solana / Bitcoin / Stellar / TRON、SIWE/SIWX 配置项以及customRpcUrls、connectorTypeOrder、enableReconnect等高频初始化参数的源码级行为。读完即可在自己的 dApp 中按版本能力清单进行升级评估与参数调优。一、CLI 工具本身安装、运行与实现原理1.1 包结构与命令入口CLI 包位于 packages/cli核心文件为package.json包名reown/appkit-cli通过bin.appkit-cli注册命令行入口依赖仅三个——figletASCII 横幅、inquirer交互式提问、tigedGitHub 模板仓库拉取器。index.js程序入口先打印banner横幅然后依次询问框架、项目名、连接库最后克隆模板。utils.jscheckDirectoryExists/generateRepoUrl/cloneRepository/runReactNativeCLI等核心逻辑。1.2 安装与运行按 packages/cli/README.md 的说明本地开发可通过npm link全局注册命令npm install sudo npm link之后即可全局使用appkit-cli [project-name]也可以不安装直接运行npx appkit-cli交互流程源自 index.js先选择框架Next.js/React/Vue/Javascript/React Native若未在命令行传入项目名则提示输入项目名并校验目录是否已存在存在则要求换名再选择连接库Wagmi/Ethers/Solana/Bitcoin/Multichain拉取对应模板输出后续三条命令cd name、npm install、npm run dev提示前往 Reown Dashboard 创建个人ProjectId仅 localhost 环境可用。1.3 模板映射与克隆实现utils.js 中的generateRepoUrl是模板映射的核心例如Next.jsWagmi→reown-com/appkit-web-examples/nextjs/next-wagmi-app-routerReactEthers→reown-com/appkit-web-examples/react/react-ethersVueSolana→reown-com/appkit-web-examples/vue/vue-solanaJavascriptBitcoin→reown-com/appkit-web-examples/javascript/javascript-bitcoin克隆过程使用tiged(repoUrl, { disableCache: true, force: true })直接拉取示例模板若选择 React Native则委托给npx reown/appkit-react-native-cli --no-banner可通过appkit-cli my-rn-app传入项目名。这些模板仓库在 web3modal 仓库中也有对应实现例如 examples/next-wagmi-app-router、examples/react-ethers、examples/vue-solana可直接在仓库内查看模板的完整代码。二、Headless 无头模式程序化钱包连接的完整 API1.8.19 ~ 1.8.24这是本版本区间最重要的能力升级方向让非 React 宿主例如walletconnect/pay-appkit无需引入任何 React Hook也能完成钱包列表获取、搜索、分页、WalletConnect URI 读取与程序化连接。2.1 实例级方法全家桶1.8.19 引入根据 CHANGELOG 1.8.19 的记录AppKit实例新增fetchWallets(options?)获取/搜索/分页钱包列表getWalletList()读取当前钱包列表快照subscribeWalletList(cb)订阅列表变化getWalletConnectUri(options?)读取 WalletConnect URIconnectWallet(wallet, namespace?, options?)程序化连接注入式 / API / 移动端 deeplink。这些方法在 appkit-base-client.ts 中逐一实现并全部委托给 controllers 包中新增的HeadlessWalletUtilHeadlessWalletUtil.ts。从源码注释看此前这套逻辑只存在于useAppKitWalletsReact Hook 内部将其上提后Hook 与客户端方法共享同一条经过测试的代码路径避免了引入reown/appkit-controllers可能解析到不同 valtio 单例的问题。2.2 1.8.20钱包列表选项扩展fetchWallets()新增两个选项includePayOnly默认过滤掉仅支持 WalletConnect Pay、但不兼容 v2 的钱包开启后将其纳入列表sort: wcpay将支持 WalletConnect Pay 的钱包置顶。对应类型定义见 HeadlessWalletUtil.ts 中的FetchWalletsOptionspage/search/entries/badge/include/exclude等字段均有 JSDoc 注释。2.3 1.8.22URI 读取 API 与 Breaking Change新增getWalletConnectUri()与subscribeWalletConnectUri()直接读取连接层状态无需引入 React Hook破坏性变更原有的命令式预取方法getWalletConnectUri()更名为prefetchWalletConnectUri()把getWalletConnectUri让位给新的读取方法同时新增resetWalletConnectUri()与resetConnectingWallet()两个重置方法1.8.22分别透传HeadlessWalletUtil.resetWcUri()与resetConnectingWallet()用于 QR 关闭或连接取消时清理状态。2.4 1.8.24pairing 过期时间透传与连接失败修复1.8.24 重点修复了 Headless 宿主的两处痛点wcError不再“卡死”此前wcError只有成功移动端 deeplink 或 headful 模式“try again”按钮才会被清除导致一次失败后所有后续尝试都显示失败。现在每次新的connectWalletConnect尝试都会从干净的错误状态开始deeplink 前校验配对 URIConnectionControllerUtil.onConnectMobile在没有 pairing URI 时是空操作断开会清除它。现在connectWallet/useAppKitWallets的connect在缺少 URI 时通过ConnectionControllerUtil.assertWcUriForDeeplink直接 reject宿主可先预取 URI 再重试而不是干等一个永远不会触发的重定向。同时在快照中透出wcPairingExpirygetWalletConnectUri()现在返回{ wcUri, wcError, wcFetchingUri, wcPairingExpiry }。源码层面ConnectionController.setUri每次都会把过期时间戳设为四分钟后见 ConnectionController.ts 中state.wcPairingExpiry CoreHelperUtil.getPairingExpiry()scaffold-ui早已用它判断是否重连这次只是补上了 Headless 侧的读取通道。这对“先取 URI、稍后再 deeplink”的宿主至关重要——配对有效期只有约 4 分钟快照里再无其他字段能区分新鲜 URI 与失效 URI。// 无头宿主典型用法方法签名源自 HeadlessWalletUtil.ts await appKit.prefetchWalletConnectUri() const { wcUri, wcError, wcFetchingUri, wcPairingExpiry } appKit.getWalletConnectUri() const unsubscribe appKit.subscribeWalletConnectUri(() { const snapshot appKit.getWalletConnectUri() // 渲染 QR 或发起 deeplink }) // 连接某个钱包注入式 / API / 移动端 deeplink await appKit.connectWallet(walletItem, eip155) // 关闭 QR 后清理 appKit.resetWalletConnectUri()从 HeadlessWalletUtil.ts 的connect实现可以看出连接分派逻辑钱包为注入式且存在对应 connector →ConnectorControllerUtil.connectExternal找不到 connector 但存在 fallback按钱包 id / explorerId 匹配如 Base Account 打开 Coinbase web 钱包→connectExternal移动端存在mobile_link时先assertWcUriForDeeplink再onConnectMobile否则走MobileWalletUtil.handleMobileDeeplinkRedirect桌面端兜底connectWalletConnect({ cache: never })。三、多链能力扩展Stellar 与 TRON 适配器1.8.24 / 1.8.223.1 Stellar 适配器正式加入1.8.241.8.24 通过新的reown/appkit-adapter-stellar包加入 Stellar 支持网络stellar:pubnet与stellar:testnetRPC 方法stellar_signXDR、stellar_signAndSubmitXDR、stellar_signMessage、stellar_signAuthEntry附带一个针对SEP-53签名的 SIWX verifier连接方式仅支持 WalletConnect无扩展钱包支持。仓库中的实现位于 packages/adapters/stellar核心类为 adapter.tsStellarAdapternamespace 为ConstantsUtil.CHAIN.STELLAR与 StellarWalletConnectConnector.ts。从 adapter.ts 的signMessage实现看签名经由 WalletConnect connector 的signMessage完成而 XDR 类操作signXDR/signAndSubmitXDR走 connector 的另一条路径。3.2 TRON 适配器修复与 v1 载荷格式1.8.24 / 1.8.221.8.24 修复了 TRON 连接在页面刷新时被静默清除的问题当 TronLink 等钱包适配器在 boot 同步时仍处于readyState解析中已存储的 TRON 连接会被抹掉。修复后TronAdapter.syncConnectors见 packages/adapters/tron/src/adapter.ts会等待 pending 的钱包适配器稳定后再做 boot 连接同步但仅当该适配器确有已存储的 TRON 连接可恢复避免给每次页面加载增加不必要的延迟useAppKitAccount因此能正确 rehydrate。1.8.22 修复了tron_signTransaction的载荷结构connector 现在尊重钱包的tron_method_version会话属性——默认发送规范要求的旧版嵌套transaction.transaction结构只有钱包在sessionProperties中声明tron_method_version: v1时才发送简化扁平结构。实现见 TronWalletConnectConnector.ts判断逻辑为this.provider.session?.sessionProperties?.[tron_method_version] v1并有对应单测 TronWalletConnectConnector.test.ts 覆盖两种形状。四、连接体验与钱包渲染修复1.8.x 高频修复点4.1 Sign 模态框按钮溢出1.8.24修复 Sign 模态框 Cancel/Sign 按钮在同时显示加载文案时渲染到模态框边界之外的问题——wui-button现在可作为 flex 子项收缩超出时用省略号截断标签而非溢出自身边界。4.2 默认钱包图标与下载 CTA1.8.24Sign In 消息请求中的默认钱包图标放大“Dont have X?” 下载 CTA 不再强制把钱包名截断为 12 字符而是显示完整钱包名。4.3 SIWX 多链钱包签名竞态1.8.24修复 Trust Wallet、SafePal 等多链钱包在消息创建与签名之间切换了活动 namespace时 SIWX 签名失败的问题fix(siwx): resolve multichain wallet signing race condition。4.4 Coinbase 4100 错误自动恢复1.8.23AppKit 自动恢复auto-restore会话后Coinbase Wallet SDK provider 仍保留账户但内部授权丢失直接调用.request()会得到 EIP-11934100Must call eth_requestAccounts before other methods。1.8.23 在 provider 注册缝syncProvider中包装 Coinbase eip155 provider以 connectorid为键——该 id 在 wagmi、ethers、ethers5 适配器间稳定触发一次一次性恢复单次eth_requestAccounts重新授权在eth_sendTransaction重试前重新断言活动链避免握手重置 SDK 链后在错误网络上广播交易只重试一次。非4100错误、用户拒绝重新授权、非 Coinbase provider 均不受影响且包装器按 provider 实例缓存以保证引用稳定。4.5 coinbasePreference 选项回归修复1.8.23修复coinbasePreference被忽略的问题all与eoaOnly现在正确使用coinbaseWalletconnector含 QR 码支持而非始终使用baseAccountsmartWalletOnly使用baseAccount。该回归由 PR #5269 引入。4.6 连接事件与最近钱包1.8.6 ~ 1.8.5CONNECT_SUCCESS事件新增walletRank属性并新增appkit/recent_walletlocalStorage 键跟踪最近连接的钱包用户拒绝连接时不再记录CONNECT_ERROR改为新的USER_REJECTED事件拒绝交易时不再记录SEND_ERROR改为SEND_REJECTED。五、初始化配置项从customRpcUrls到enableReconnect1.7.x以下配置项虽来自 1.7.x但仍是当前版本1.8.x初始化参数体系的基础且都能在 OptionsController.ts 中找到对应状态字段。5.1customRpcUrls覆盖默认 RPC1.7.1以 CAIP 网络 ID 为键、URL 数组为值覆盖网络默认 RPCconst customRpcUrls { eip155:1: [{ url: https://your-custom-mainnet-url.com }], eip155:137: [{ url: https://your-custom-polygon-url.com }] } const modal createAppKit({ adapters: [...], networks: [...], projectId: project-id, customRpcUrls })若同时使用 Wagmi 适配器需将同样的customRpcUrls传给new WagmiAdapter({ ... })。还可以为传输层传入 fetch 配置const customRpcUrls { eip155:1: [ { url: https://your-custom-mainnet-url.com, config: { fetchOptions: { headers: { Content-Type: text/plain } } } } ] }5.2enableReconnect关闭自动重连1.7.11createAppKit({ networks: [...], metadata: {...}, enableReconnect: false // 关闭初始化与页面加载时的自动重连 })1.7.15 还修复了enableReconnect: false时初始化不同步的问题。5.3connectorTypeOrder自定义连接器展示顺序1.7.13const modal createAppKit({ adapters: [], networks: [], projectId: YOUR_PROJECT_ID, features: { connectorTypeOrder: [injected, walletConnect, recent] } })数组顺序即展示顺序上例中注入式钱包在前随后是 WalletConnect最后是最近钱包。底层实现在 ConnectorUtil.ts 的getConnectorTypeOrder它会先按walletConnect/recent/injected含 announced、multiChain/featured/custom/external/recommended计算“已启用”类型集合再把overriddenConnectors即features.connectorTypeOrder中启用的类型优先排列其余类型按默认顺序补在后面。5.4 其余常用开关配置项说明引入版本enableWalletGuide: false关闭社交/邮箱登录启用时的钱包引导页脚1.6.0enableAuthLogger: false关闭邮箱/社交登录日志默认 true1.6.3enableNetworkSwitcher: false关闭模态框中的网络切换1.7.2enableEIP6963控制 wagmi 适配器 EIP-6963 行为曾修复其失效问题1.7.11registerWalletStandard自动将 WalletConnect relay connector 注册为 Wallet Standard 钱包1.7.11signOutOnDisconnectSIWXConfig断开连接时是否登出1.7.12六、SIWE / SIWX 与账户 API 演进6.1 SIWErequired选项1.6.4export const siweConfig createSIWEConfig({ required: false, // 可选默认 true getMessageParams: async () { /* ... */ }, createMessage: ({ address, ...args }) { /* ... */ }, getNonce: async () { /* ... */ }, getSession: async () { /* ... */ }, verifyMessage: async ({ message, signature }) { /* ... */ }, signOut: async () { /* ... */ } })required: true默认时用户拒绝签名请求会断开钱包并关闭模态框false时仅关闭模态框、不断开钱包。6.2 账户状态 APIuseAppKitAccount({ chainNamespace })支持按链获取账户状态eip155/solana/bip1221.6.9useAppKitAccount返回embeddedWalletInfo含user?.email等1.6.4appKit.getAccount公开方法1.7.0appKit.disconnect()不传参时断开所有 namespace可传{ namespace: solana }只断开指定链1.7.1新增getDisabledCaipNetworks读取被禁用的 CAIP 网络1.8.9。6.3 事件监听与取消订阅1.8.17为 AppKit 事件监听器补充unsubscribe函数避免重复监听造成回调堆积。七、wallet-button 组件多链 namespace 支持1.7.17wallet-button 升级为多链支持通过namespace属性区分链React 组件const wallets [ { wallet: metamask, namespace: eip155, label: MetaMask EVM }, { wallet: metamask, namespace: solana, label: MetaMask Solana }, { wallet: phantom, namespace: bip122, label: Phantom Bitcoin } ] wallets.map(({ wallet, namespace }) ( AppKitWalletButton key{${wallet}-${namespace}} wallet{wallet} namespace{namespace} / ))React Hookconst { data, error, isPending, isSuccess, isError, connect } useAppKitWallet({ namespace: eip155, // solana 或 bip122 用于其他链 onError: err {}, onSuccess: data {} }) button onClick{() connect(walletConnect)}Open QR modal/button button onClick{() connect(metamask)}Connect to MetaMask/buttonVanilla JSscript typemodule import reown/appkit-wallet-button import { createAppKitWalletButton } from reown/appkit-wallet-button const wallet createAppKitWalletButton({ namespace: eip155 }) wallet.subscribeIsReady(({ isReady }) { if (!isReady) return document.querySelectorAll(button[data-wallet]).forEach(button { button.disabled false button.onclick () wallet.connect(button.getAttribute(data-wallet)) }) }) /script appkit-wallet-button walletmetamask namespaceeip155/appkit-wallet-button button>赞分享区块链前端认证鉴权【免费下载链接】web3modalThe full stack toolkit to build onchain app UX项目地址https://gitcode.com/gh_mirrors/we/web3modal点击查看免费下载相关推荐AReaL 中的 PPO/GRPO 算法家族从 GRPO 到 DAPO、SAPO、GSPO 的配置切换与源码原理AReaL 中的 PPO/GRPO 算法家族从 GRPO 到 DAPO、SAPO、GSPO 的配置切换与源码原理 本文以 docs/en/algorithms区块链前端认证鉴权Web3Modal AppKit 钱包按钮reown/appkit-wallet-button完全指南从 Web Component 到 React Hook 的多链连接实战Web3Modal AppKit 钱包按钮reown/appkit wallet button完全指南从 Web Component 到 React H区块链前端认证鉴权创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考