@rainbow-me/rainbowkit 与 wagmi、ethers 的命名格式差异，主要源于 npm 包的两种不同命名规范：作用域包（Scoped Package） 和 普通包。这种差异背后有明确的设计意图和实践考量，具体分析如下：

1. 命名格式差异的本质

• @rainbow-me/rainbowkit：使用了 作用域包 格式（@组织名/包名）
• wagmi、ethers：使用了 普通包 格式（直接包名）

2. 为什么 @rainbow-me/rainbowkit 使用作用域包？

作用域包（以 @ 开头）是 npm 提供的一种命名空间机制，主要用于：

（1）品牌与归属明确化

• 组织标识：@rainbow-me 是 Rainbow Wallet 团队的官方 npm 组织名，明确标识了该包的开发和维护主体
• 品牌一致性：与 Rainbow Wallet 钱包应用的品牌保持统一，增强用户和开发者的信任感
• 避免命名冲突：即使其他开发者想创建名为 rainbowkit 的包，也不会与官方包冲突

（2）包管理的规范化

• 权限控制：只有 Rainbow Wallet 团队的成员才能发布和更新 @rainbow-me 作用域下的包
• 版本管理：便于团队内部统一管理多个相关包（如可能存在的 @rainbow-me/utils、@rainbow-me/hooks 等）
• 生态系统构建：为未来扩展其他相关工具包预留了命名空间

3. 为什么 wagmi 和 ethers 使用普通包？

普通包（直接包名）通常适用于以下场景：

（1）wagmi 的情况

• 独立工具库定位：wagmi 是一个通用的以太坊 React Hooks 库，不隶属于特定组织或产品
• 简洁性优先：直接使用 wagmi 作为包名更简洁易记，符合其作为基础工具库的定位
• 社区驱动：强调其跨项目、跨生态的通用性，适合所有以太坊前端开发者使用

（2）ethers 的情况

• 历史原因：ethers 是以太坊生态中较早的核心库之一，在作用域包广泛使用前就已存在
• 行业标准地位：作为以太坊官方推荐的 JavaScript 库，直接使用 ethers 已成为行业共识
• 全球知名度：无需通过组织名来增强辨识度，ethers 本身就是以太坊开发的标志性库

4. 命名格式差异的意义

这种命名差异反映了前端 Web3 生态中包管理的不同策略：

5. 总结

• @rainbow-me/rainbowkit 使用作用域包：突出品牌归属，适合作为 Rainbow Wallet 生态的一部分
• wagmi 和 ethers 使用普通包：强调通用性和简洁性，适合作为跨项目的基础工具

这种命名差异并非技术优劣之分，而是根据项目定位、维护主体和使用场景选择的不同策略，体现了 npm 包管理系统的灵活性和适应性。

主流公链对比（生产环境）

主流测试链对比（开发/联调）

选链建议（简版）

• 想要最稳和最大生态：Ethereum + Arbitrum/Optimism/Base
• 想要低费和高频交互：BSC / Polygon / Solana
• 想做 EVM 且方便迁移：优先 Arbitrum / Base / OP
• 想提前布局 ZK：zkSync / Linea

1. 核心定位与层级关系

四者分属不同层级，服务于以太坊 Web3 前端开发的不同需求：

2. 详细功能对比

（1）ethers.js

• 核心功能：
  • 钱包管理（生成、导入、签名交易）
  • 智能合约交互（部署、调用、监听事件）
  • 网络连接（与以太坊节点通信）
  • 以太坊数据解析（地址、交易、区块等）
• 特点：
  • 轻量级（体积小，按需引入）
  • API 现代（使用 Promise，支持 async/await）
  • TypeScript 友好
  • 文档清晰，社区活跃
• 使用场景：
  • 需要直接与以太坊区块链交互的项目
  • 对包体积敏感的应用
  • 追求现代 API 设计的开发者

（2）web3.js

• 核心功能：
  • 与 ethers.js 类似，提供全面的以太坊交互功能
  • 支持更多底层 RPC 方法
  • 内置更多工具函数
• 特点：
  • 功能全面（官方维护，覆盖所有以太坊功能）
  • 相对较重（包体积大）
  • API 设计较传统（早期版本使用回调，新版支持 Promise）
  • 历史悠久，生态成熟
• 使用场景：
  • 需要使用官方全功能实现的项目
  • 传统 Web3 项目迁移
  • 对官方支持有强依赖的场景

（3）viem

• 核心功能：
  • 与 ethers.js 类似，提供以太坊交互的核心功能
  • 支持 EIP-1193 钱包标准
  • 内置链数据和地址工具
• 特点：
  • 极致轻量（体积比 ethers.js 更小）
  • 性能优化（更快的交易签名和网络请求）
  • 现代 API 设计（链式调用，类型安全）
  • 专注于前端使用场景
• 使用场景：
  • 对包体积和性能要求极高的项目
  • 现代前端框架（如 React 18+）
  • 追求最新技术栈的开发者

（4）wagmi

• 核心功能：
  • 基于 React Hooks 的以太坊交互封装
  • 钱包连接与管理（支持多种钱包）
  • 智能合约调用的 Hook 化（如 useContractRead）
  • 交易发送与状态管理
  • 与 @tanstack/react-query 集成，提供数据缓存
• 特点：
  • 前端开发友好（Hooks 化 API）
  • 支持多底层库（默认支持 viem，可选 ethers.js）
  • 与现代前端生态集成（React、TypeScript）
  • 配置灵活，扩展性强
• 使用场景：
  • React 前端 Web3 项目
  • 需要快速实现钱包连接、合约交互的场景
  • 追求开发效率和代码简洁的项目

3. 联系与依赖关系

• 底层库之间的关系：

  • ethers.js、web3.js、viem 均为底层以太坊交互库，功能重叠但设计理念和性能不同
  • viem 是较新的库，针对前端场景优化，体积和性能优于传统库

• wagmi 与底层库的关系：

  • wagmi v1+ 默认使用 viem 作为底层库（替代之前的 ethers.js）
  • 仍支持通过配置使用 ethers.js（兼容性考虑）
  • wagmi 将底层库的复杂逻辑封装为简洁的 React Hooks

• 功能互补：

  • 底层库（ethers.js/web3.js/viem）负责与区块链交互的核心逻辑
  • 上层库（wagmi）简化前端开发，提供 Hooks 化 API 和状态管理

• 生态组合：

  • 现代 Web3 前端开发的主流组合：viem + wagmi + RainbowKit（或其他钱包连接库）
  • 传统组合：ethers.js/web3.js + 自定义钱包连接逻辑

4. 技术演进与选择建议

• 技术趋势：

  • 从 web3.js 到 ethers.js：追求更现代、轻量的 API
  • 从 ethers.js 到 viem：进一步优化性能和体积
  • 从直接使用底层库到 wagmi：提升前端开发效率

• 选择建议：

  • 现代前端项目：推荐使用 viem + wagmi 组合
    • 优势：极致轻量、性能优异、开发效率高
  • 需要兼容性：选择 ethers.js + wagmi
    • 优势：生态成熟、文档丰富、社区支持广
  • 传统项目：继续使用 web3.js
    • 优势：官方维护、功能全面、历史兼容性好
  • 底层定制需求：直接使用 viem 或 ethers.js
    • 优势：灵活性高，可按需实现特定功能

5. 总结

• 底层库（ethers.js/web3.js/viem）：负责与以太坊区块链交互的核心逻辑，选择依据为性能、体积和 API 偏好
• 上层库（wagmi）：简化前端开发，提供 Hooks 化 API 和状态管理，大幅提升开发效率
• 最佳实践：现代项目优先选择 viem + wagmi 组合，兼顾性能和开发体验

这种分层设计反映了 Web3 前端开发的演进趋势：从复杂的底层操作到简洁的上层抽象，从单一功能库到系统化的生态工具链。

一句话结论

• Provider 的 getBalance 查的是地址的原生币余额。
• Contract（如 ERC20）里的 balanceOf 查的是地址在该合约中的 Token 余额。

1) Provider：getBalance(address)

含义

查询某个地址当前持有的原生代币数量。

典型场景

• 查询 EOA 钱包地址的 ETH 余额
• 查询合约地址持有的 ETH（比如某个合约金库里的 ETH）

关键点

• 不关心该地址是否是 EOA/Contract，统一按“地址的原生币”查询
• 不能直接查 ERC20（USDT/WETH/DAI）余额

示例

1
2

const eth1 = await provider.getBalance("0xEOA...");
const eth2 = await provider.getBalance("0xContract...");

2) Contract：balanceOf(address)（以 ERC20 为例）

含义

查询某地址在某个 Token 合约账本中的余额。

典型场景

• 查询用户的 USDT/WETH/DAI 余额
• 查询某地址在指定 ERC20 里的持仓

关键点

• 必须先确定“哪一个 token 合约”
• 同一个地址在不同 token 合约中的余额互不影响

示例

1
2
3
4
5

const usdt = new ethers.Contract(USDT_ADDR, erc20Abi, provider);
const weth = new ethers.Contract(WETH_ADDR, erc20Abi, provider);

const usdtBalance = await usdt.balanceOf("0xUser...");
const wethBalance = await weth.balanceOf("0xUser...");

3) 对比表

4) 常见误区澄清

• 误区：给 provider.getBalance 传 token 合约地址，就能得到该 token 总余额。
  实际：得到的是“这个合约地址持有的原生币余额”，不是 token 余额。

• 误区：provider 不能查合约地址余额。
  实际：可以查，但查的是该合约地址的原生币余额。

5) 记忆口诀

• 原生币 -> provider.getBalance
• 合约资产 -> contract.xxx(...)（ERC20 用 balanceOf）