Ethers.js：以太坊客户端库，支持合约交互与钱包管理

为什么需要 Ethers.js：手写 JSON-RPC 与签名的成本太高

直接对接以太坊节点，开发者需要自己构造 JSON-RPC 请求（eth_call、eth_sendRawTransaction）、处理私钥签名（secp256k1 曲线、RLP 编码）、把函数签名转成 4 字节选择器并做 ABI 编解码。“把 1 ETH 转给某地址”这条最简单的路径，就要完成 gas 估算、nonce 管理、签名、序列化、广播、轮询回执六个步骤，每一步都容易出错，而且与业务逻辑无关。

Ethers.js 将上述过程收敛为三层抽象：Provider 负责与节点通信（读取链上数据、广播交易）；Signer（通常由 Wallet 实现）负责账户与签名；Contract 负责合约的 ABI 编解码与调用。开发者只需 provider.getBalance(addr) 读取余额、wallet.sendTransaction({to, value}) 发送交易、contract.balanceOf(addr) 调用合约只读方法——底层细节全部由库处理，错误率与代码量同时下降。

与 web3.js 相比，Ethers.js 在 v6 后全面拥抱 TypeScript 与原生 bigint，类型推导更可靠、包体积更小；与 viem 相比，ethers 的面向对象风格更直观，历史教程与存量代码更多，至今仍是大多数课程、工具链（如 Hardhat 生态）的默认选择。

安装与环境配置：3 步就绪

Ethers.js 需要 Node.js 14+（建议 18+）。在项目目录内执行以下命令完成初始化、安装与验证。

步骤一：初始化项目并安装依赖。步骤二：打印版本号确认安装成功，v6 应输出 6.x.x。步骤三：连接公共 RPC 读取主网最新区块高度，验证网络通路可用。浏览器端也可用官方 CDN 的 UMD 包（https://cdn.ethers.io/lib/ethers-6.13.umd.min.js，版本号按需替换）直接引入。

npm init -ynpm install ethers # 验证版本（ESM 方式）node --input-type=module -e "import { ethers } from 'ethers'; console.log(ethers.version);" # 连接公共节点读取区块高度，验证链上通路node --input-type=module -e "import { ethers } from 'ethers';const provider = new ethers.JsonRpcProvider('https://cloudflare-eth.com');console.log('最新区块:', await provider.getBlockNumber());"

快速上手：5 分钟读取余额并发送一笔交易

最小可用流程：连接网络（Provider）→ 读取链上数据 → 用钱包（Wallet）签名广播交易 → 等待回执（wait）。

1. 在项目根目录创建 demo.mjs（ESM 模块），引入 ethers。

2. 创建 Provider：new ethers.JsonRpcProvider('https://cloudflare-eth.com')，也可替换为 Infura/Alchemy 的带 key 地址。

3. 用 provider.getBalance(地址) 读取余额，ethers.formatEther 把 wei（ETH 最小单位，1 ETH = 10^18 wei）显示为 ETH 字符串。

4. 用私钥创建 Wallet 并指定网络：new ethers.Wallet(process.env.PRIVATE_KEY, provider)。

5. 调用 wallet.sendTransaction({to, value})，value 用 ethers.parseEther('0.001') 转为 wei。

6. await tx.wait() 等待区块确认，从回执读取 status 与 gasUsed。

进阶技巧：主网发送会消耗真实 ETH，建议先在 Sepolia 测试网联调（RPC 地址与测试币 faucet 向 RPC 服务商索取），流程验证通过后再切主网。

import { ethers } from 'ethers'; // 1. 连接以太坊主网（也可替换为 Infura/Alchemy 私有地址）const provider = new ethers.JsonRpcProvider('https://cloudflare-eth.com');console.log('最新区块高度:', await provider.getBlockNumber()); // 2. 读取余额。formatEther 把 wei（bigint）转为 ETH 字符串const vitalik = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';const wei = await provider.getBalance(vitalik);console.log('Vitalik 余额:', ethers.formatEther(wei), 'ETH'); // 3. 用私钥创建钱包（务必使用环境变量，勿硬编码）const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); // 4. 发送交易。parseEther 把 ETH 字符串转为 wei（bigint）const tx = await wallet.sendTransaction({  to: '0xRecipientAddressHere',  value: ethers.parseEther('0.001'),});console.log('交易广播成功，hash:', tx.hash); // 5. 等待确认。receipt.status === 1 表示执行成功const receipt = await tx.wait();console.log('已确认，区块:', receipt.blockNumber, 'gas 消耗:', receipt.gasUsed.toString());

核心能力详解：5 大支柱

支柱一·Provider 网络接入：Provider 抽象对节点的全部读写操作。v6 提供 JsonRpcProvider（HTTP 轮询）、WebSocketProvider（实时推送）、FallbackProvider（多路容灾，支持权重与超时配置）、BrowserProvider（包装浏览器注入的 EIP-1193 钱包）。常用读接口有 getBlockNumber、getBalance、getTransactionReceipt；写接口 broadcastTransaction 负责将签名后的交易广播上链。

支柱二·Wallet 账户与签名：Wallet 实现 Signer 接口，持有私钥并负责签名。创建方式：new Wallet(privateKey)、Wallet.createRandom()、HDNodeWallet.fromPhrase(mnemonic, path)（BIP-39/BIP-44 助记词派生，一条助记词可派生无限多账户）。签名能力包括 signMessage（消息签名）与 signTypedData（EIP-712 结构化签名，常用于登录授权与 Permit 免 gas 授权）。

支柱三·Contract 合约交互：new ethers.Contract(address, abi, runner)，runner 传 Provider 则只读、传 Signer 则可写。view 函数直接返回结果值；写函数返回 TransactionResponse，必须 .wait() 拿回执；payable 函数可在调用参数中附带 { value }。v6 支持人类可读 ABI（如 ['function transfer(address to, uint256 amount) returns (bool)']），无需手抄 JSON ABI。

支柱四·事件监听与日志解析：contract.on('Transfer', cb) 订阅实时事件；provider.getLogs(filter) 按区块范围回溯历史日志；事件参数按 ABI 自动解码（如 from、to、value）。数据中心型应用常用 WebSocketProvider 配合 checkpoint 记录已处理区块，断线后回扫补漏。

支柱五·数据编解码与工具函数：formatUnits/parseUnits 完成任意 ERC-20 代币的小数与最小单位换算；getAddress 校验并统一地址校验和；Interface 负责函数选择器与事件 topic 的编解码；keccak256、hexlify 等用于文件哈希上链、构造原始数据等场景。

生产部署与监控：从上线到运维

多 RPC 容灾：单一路 RPC 在限流或宕机时直接导致服务不可用。生产建议用 FallbackProvider 组合多家供应商，按权重分配并设置单次请求的 stallTimeout（超时阈值）：

事件监听服务：使用 WebSocketProvider 订阅合约事件，进程内维护 lastSyncedBlock，每处理一批日志更新 checkpoint 并持久化（Redis/数据库）；断线重连后从 checkpoint 区块高度调用 getLogs 回扫，避免漏数据。服务保持无状态，把进度放到外部存储以便水平扩容。

可观测性：所有交易操作记录 hash、nonce、gas 上限、实际 gasUsed 与确认耗时；对 wait() 超时和 status !== 1 的交易上报告警；采集 Provider 层的请求失败率、429 限流次数等指标接入 Prometheus/Sentry。私钥只存于后端环境变量或 KMS 签名服务，前端永不接触。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>v5 代码直接迁移 v6 会大量报错：BigNumber 与 ethers.utils 命名空间已移除，wei 值变为原生 bigint，务必先读官方迁移指南再改业务代码。</li><li>只 await sendTransaction 不调 wait()：交易仅代表广播成功，未确认不算成功，必须 await tx.wait() 并校验 receipt.status === 1。</li><li>私钥写死在前端或提交到 Git：任何拿到代码者都能转走资产，私钥应只放后端环境变量或托管签名服务。</li><li>生产裸用免费公共 RPC：限流频繁导致请求失败，建议 FallbackProvider 多路容灾或自建节点。</li><li>WebSocket 断线后事件会静默丢失：必须记录 lastSyncedBlock 检查点，重连后调用 getLogs 回扫补漏。</li></ul>

const provider = new ethers.FallbackProvider([  { provider: process.env.INFURA_URL, weight: 2, stallTimeout: 5000 },  { provider: process.env.ALCHEMY_URL, weight: 2, stallTimeout: 5000 },  { provider: 'http://localhost:8545', weight: 1, stallTimeout: 10000 },]);

版本迭代

Ethers.js 自 2016 年发布 v1，经历 2019 年 v4 的 ABI/事件系统重写、2020 年 v5 全面 TypeScript 化与模块化、2023 年 v6 以 bigint 取代 BigNumber 并扁平化 API 的三次大版本演进。v5 进入长期维护，v6 自 2023 年起经多次小版本打磨，截至训练数据最新为 6.13.x（2024 年 10 月发布，后续持续有补丁更新，本文撰写时可能已有更新版本）。

AI 应用场景

常见误区

面试题

参考来源

• webpageEthers.js 官网项目入口与版本概览