使用 Web3Modal 与 React 集成 web3.js从钱包连接到智能合约交互完整指南【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js本指南将带你完整走一遍在 React 项目中集成 Web3Modal 与 web3.js 的流程从安装依赖、初始化 Web3Modal 实例、配置链与元数据到触发钱包连接弹窗最后使用钱包注入的 Provider 创建Web3实例并调用智能合约方法。读完本文你将能够独立搭建一个支持钱包连接、多钱包发现EIP-6963与合约交互的现代 React DApp。前置了解Web3Modal 与 web3.js 的分工Web3Modal 是一个由 WalletConnect 提供的 SDK它让 DApp 可以轻松地与各类钱包建立连接并为「签名交易」「与链上智能合约交互」等操作提供一个简单直观的界面。在本项目中Web3modal 指南入口 明确将主题定义为使用 web3.js 配置 WalletConnect钱包连接、链切换等体验层逻辑交给 Web3Modal 处理而真正与以太坊 JSON RPC 交互、调用合约方法的工作则交给 web3.js 完成。二者的技术分工可以从 web3.js 的入口导出看到packages/web3/src/index.ts 从web3-core导出Web3Context从web3-eth-contract导出Contract等核心类这意味着 Web3Modal 提供的任意 EIP-1193 钱包 Provider 都可以无缝注入new Web3(provider)中使用。环境准备与依赖安装官方 React 指南docs/docs/guides/07_dapps/web3_modal_guide/react.md使用 Vite 作为本地开发服务器。安装命令如下npm install web3modal-web3js react react-dom npm install --save-dev vite vitejs/plugin-react其中web3modal-web3js面向 web3.js 适配的 Web3Modal 封装包提供createWeb3Modal、defaultConfig等核心 APIreact/react-domReact 运行时vite/vitejs/plugin-react开发服务器与 React 编译插件仅开发依赖。如需在非 React 场景使用web3modal-web3js也提供了普通 JavaScript 入口可直接npm install web3modal-web3js web3js。项目骨架创建 index.html 与入口文件在项目根目录创建index.html作为 Vite 应用的 HTML 入口!DOCTYPE html html langen head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleReact Web3 example/title /head body div idapp/div script typemodule src/src/main.tsx/script /body /html在根目录创建vite.config.js注册 React 插件import react from vitejs/plugin-react; import { defineConfig } from vite; export default defineConfig({ plugins: [react()], });最后创建 React 挂载入口src/main.tsx把根组件渲染到#app节点import React from react; import ReactDOM from react-dom/client; import App from ./App.js; ReactDOM.createRoot(document.getElementById(app)!).render( React.StrictMode App / /React.StrictMode, );初始化 Web3Modal五步配置法官方指南将核心初始化浓缩为「5 步」全部放在一个src/Web3modal.tsx或任意组件文件中完成。下面逐行拆解每个配置项的作用。1. 获取 Project IDconst projectId YOUR_PROJECT_ID;Project ID 是 WalletConnect 云服务签发的唯一标识需要到 walletconnect.com 控制台注册应用后获取。它用于中继钱包之间点对点连接的信令。2. 声明链配置const mainnet { chainId: 1, name: Ethereum, currency: ETH, explorerUrl: https://etherscan.io, rpcUrl: https://cloudflare-eth.com, };每个链对象包含chainId链 ID主网为 1、name展示名称、currency原生代币符号、explorerUrl区块浏览器用于交易链接跳转、rpcUrlRPC 节点地址供 WalletConnect 中继交易数据。3. 创建 metadata 元数据const metadata { name: My Website, description: My Website description, url: https://mywebsite.com, // origin must match your domain subdomain icons: [https://avatars.mywebsite.com/], };元数据会展示在钱包的授权确认界面中。注意url的 origin协议 域名 端口必须与你的实际部署域名及子域名一致否则钱包侧可能拒绝展示或校验失败。4. 通过 defaultConfig 创建 web3 配置const web3Config defaultConfig({ /*Required*/ metadata, /*Optional*/ enableEIP6963: true, // true by default enableInjected: true, // true by default enableCoinbase: true, // true by default rpcUrl: ..., // used for the Coinbase SDK defaultChainId: 1, // used for the Coinbase SDK });defaultConfig是适配 web3.js 的关键桥接函数它把钱包能力配置封装成 Web3Modal 内部可识别的配置对象metadata必填第 3 步创建的元数据enableEIP6963是否启用 EIP-6963 多注入钱包发现协议默认trueenableInjected是否启用浏览器注入的钱包如 MetaMask默认trueenableCoinbase是否启用 Coinbase Wallet SDK默认truerpcUrl供 Coinbase SDK 使用的 RPC 地址defaultChainIdCoinbase SDK 的默认链 ID。其中enableEIP6963与 web3.js 的底层能力高度呼应web3.js 在 packages/web3/src/web3_eip6963.ts 中实现了完整的 EIP-6963 支持通过requestEIP6963Providers()主动向浏览器广播eip6963:requestProvider事件、收集钱包应答通过onNewProviderDiscovered(callback)订阅web3:providersMapUpdated事件从而动态发现并注入多个钱包 Provider。这也解释了为什么 Web3Modal 的enableEIP6963默认开启——它天然兼容 web3.js 的多钱包发现模型。5. 创建 Web3Modal 实例createWeb3Modal({ web3Config, chains: [mainnet], projectId, enableAnalytics: true, // Optional - defaults to your Cloud configuration });createWeb3Modal接收三个核心参数web3Config上一步的配置、chains支持的链数组、projectId第 1 步获取的 IDenableAnalytics为可选项用于开启使用数据上报默认跟随 WalletConnect 云端配置。初始化完成后你的组件就可以像下面这样被引用export default function App() { return YourApp /; }触发连接弹窗一行 JSX 搞定初始化完成后无需手写任何连接逻辑Web3Modal 提供了开箱即用的 React 组件w3m-button/把它放进任意组件即可渲染出连接钱包按钮并弹出钱包选择界面export default function ConnectButton() { return w3m-button/ }获取钱包 Provider 并与合约交互连接成功后Web3Modal 的 React Hooks 会暴露当前钱包状态与 Provider。官方入门指南index.mdx给出了一个完整的「读取 USDT 余额 合约名」示例import Web3 from web3; import { ERC20ABI } from ./contracts/ERC20; const USDTAddress 0xdac17f958d2ee523a2206206994597c13d831ec7; function Components() { const { isConnected } useWeb3ModalAccount() const { walletProvider } useWeb3ModalProvider() const [USDTBalance, setUSDTBalance] useState(0); const [smartContractName, setSmartContractName] useState(); async function getContractInfo() { if (!isConnected) throw Error(not connected); const web3 new Web3({ provider: walletProvider, config: { defaultNetworkId: chainId }, }); const contract new web3.eth.Contract(ERC20ABI, USDTAddress); const balance await contract.methods.balanceOf(address).call(); const name (await contract.methods.name().call()) as string; setUSDTBalance(Number(balance)); setSmartContractName(name); } return button onClick{getContractInfo}Get User Balance and Contract name/button p Balance: {USDTBalance} smartContractName: {smartContractName}/p/ }这个示例背后对应了 web3.js 的几条核心机制Provider 注入new Web3({ provider: walletProvider, config: { defaultNetworkId: chainId } })是 web3.js 的标准构造方式。从源码看Web3 构造器 接受Web3ContextInitOptions形式的对象其中provider字段被写入上下文同时walletProvider正是 Web3Modal 从钱包侧获取的 EIP-1193 Provider与 eip6963.md 中将EIP6963ProviderDetail.provider注入new Web3(provider)的用法完全一致。链 ID 校验config.defaultNetworkId会与钱包实际连接的网络比对防止合约调用发往错误链。若未指定web3.js 会默认使用mainnetRPC见 web3.ts 构造器默认参数。合约调用new web3.eth.Contract(ERC20ABI, USDTAddress)由 web3.ts 中的ContractBuilder实现它与eth模块共享同一上下文与 Provider因此contract.methods.balanceOf(address).call()会经由当前钱包 Provider 完成 RPC 请求——既可能是只读查询也可能是需要用户签名的写交易。ABI 解析ERC20ABI传入后web3.js 会基于 ABI 生成methods的强类型调用接口这部分由web3-eth-abi包packages/web3-eth-abi完成编码与解码。结合中间态 DApp 指南加深理解本仓库的 intermediate-dapp.md 展示了不使用 Web3Modal、直接基于 EIP-6963 手动管理 Provider 的路径它同样通过new Web3(provider.provider)创建实例再调用requestAccounts获取账户、注册accountsChanged与chainChanged事件保持 UI 同步。与 Web3Modal 方案对比可以看出Web3Modal 方案把「发现钱包 → 弹窗选择 → 连接」的整套流程封装为w3m-button/与 Hooks开发成本最低手动方案适合需要完全自定义钱包选择 UI 的场景底层原理与 Web3Modal 一致均依赖 EIP-1193 / EIP-6963 Provider。常见问题与排错建议Project ID 未生效请确认projectId来自 walletconnect.com 控制台且与当前域名匹配。metadata.url 校验失败url的 origin协议 域名 子域名必须与实际部署地址一致。连接后合约调用报错检查config.defaultNetworkId是否与钱包当前网络一致确认walletProvider已就绪先判断isConnected。弹窗无法加载部分浏览器或隐私模式下若预览异常可尝试切换浏览器官方指南亦在预览说明中提示了这一点。未发现任何钱包确认浏览器已安装 MetaMask 等注入钱包且enableInjected/enableEIP6963未被关闭。小结通过本文你已经掌握了在 React Vite 项目中集成 Web3Modal 与 web3.js 的完整路径先以defaultConfigcreateWeb3Modal完成五步初始化再用w3m-button/一行代码触发钱包连接最后借助useWeb3ModalProvider拿到的钱包 Provider 直接构造Web3实例并调用智能合约。这套组合让钱包连接体验与链上交互能力各司其职是目前在 web3.js 生态中搭建 DApp 最快捷的官方推荐方式。【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考