当前位置：首页 > news >正文

Ethers.js 开发入门：核心功能、最佳实践与避坑指南

news 来源：原创 2025/5/1 22:38:43

引言

Ethers.js 是当前 Web3 开发领域增长最快、备受开发者青睐的以太坊 JavaScript 库之一。在本篇文章中，我们将介绍 Ethers.js 的核心功能和用法，包括如何连接区块链节点、与钱包交互、读取智能合约数据、发送交易等。同时，我们还将分享使用 Ethers.js 开发时的最佳实践和易踩的常见坑，帮助你快速上手并避开常见错误。

Ethers.js 简介

Ethers.js 致力于提供一个完整而精简的库，用于与以太坊区块链及其生态系统交互。它涵盖了丰富的功能模块：包括用于连接区块链节点的提供者（Provider）、管理账户和交易签名的签名者（Signer）、简化大数和格式转换的工具库（Utils），以及友好的智能合约调用接口。与传统的 Web3.js 库相比，Ethers.js 的 API 更加简洁优雅，文档完善，因此受到众多开发者的青睐，能够帮助开发者更快速地构建去中心化应用（DApp）。

连接以太坊节点（Provider）

在使用 Ethers.js 时，首先需要一个 Provider 来连接以太坊节点。Provider 负责与区块链通信，获取链上数据或发送交易至网络。Ethers.js 提供了多种 Provider 实现，可以轻松连接以太坊主网、各测试网络（如 Ropsten、Kovan、Goerli 等）或本地开发链。通常，我们会使用像 Infura 或 Alchemy 这类以太坊节点服务提供的 RPC 接口。下面是一个使用 Infura 提供的 Goerli 测试网 RPC 端点创建 Provider 的示例：

// 通过 Infura 的 Goerli 测试网 RPC 接口创建 Provider
const { ethers } = require("ethers");
const INFURA_PROJECT_ID = "你的Infura项目ID";
const provider = new ethers.providers.JsonRpcProvider(
    `https://goerli.infura.io/v3/${INFURA_PROJECT_ID}`
);

连接钱包与签名（Signer）

要对交易进行签名或执行需要账户权限的操作，我们需要一个 Signer（签名者），它代表一个以太坊账户。Signer 持有私钥，用于对交易进行数字签名。常见的 Signer 来源有两种：一种是在浏览器中通过 MetaMask 等钱包扩展提供账户，另一种是在后端脚本中直接使用私钥创建钱包对象。下面分别给出这两种场景的示例代码。

// 浏览器环境下通过 MetaMask 提供 Signer
const provider = new ethers.providers.Web3Provider(window.ethereum);
// 请确保用户已安装 MetaMask 并在此处请求授权访问账户
await provider.send("eth_requestAccounts", []);
const signer = provider.getSigner();

// Node.js 环境下使用私钥创建 Signer（Wallet）
const { ethers } = require("ethers");
const provider = ethers.getDefaultProvider("goerli");  // 使用默认提供商连接 Goerli 测试网
const PRIVATE_KEY = "你的私钥字符串";
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

读取区块链数据与智能合约

有了 Provider，我们可以直接读取链上的公共数据，例如账户余额、当前区块号等。例如，调用 provider.getBalance(地址) 可以获取某个地址的以太余额（返回一个大数 BigNumber，单位为 wei）。通常我们会使用 ethers.utils.formatEther() 将其格式化成人类可读的以太值（ETH）。下面是一个查询账户余额并格式化输出的示例：

// 查询指定地址的余额并格式化为 ETH
const userAddress = "0xABC...";  // 要查询的以太坊地址
const balanceBN = await provider.getBalance(userAddress);
console.log("账户余额:", ethers.utils.formatEther(balanceBN), "ETH");

除了基本数据读取，Ethers.js 提供了简便的接口与智能合约交互。要读取合约状态，我们需要合约的地址和 ABI（应用二进制接口）。使用 ethers.Contract 类可以根据地址和 ABI创建合约对象，然后调用其只读方法（ABI 中标记为 view 或 pure 的函数）。例如，下面演示如何获取 ERC-20 代币（如 DAI 稳定币）的名称和某账户的代币余额：

// 与 ERC-20 合约交互示例（以 DAI 稳定币为例）
const daiAddress = "0x6B175474E89094C44Da98b954EedeAC495271d0F"; // DAI 合约地址（以太坊主网）
const daiAbi = [
    "function name() view returns (string)",
    "function balanceOf(address) view returns (uint256)"
];  // 合约 ABI（这里只列出需要用到的函数）
const daiContract = new ethers.Contract(daiAddress, daiAbi, provider);
const name = await daiContract.name();
const daiBalance = await daiContract.balanceOf(userAddress);
console.log("代币名称:", name);
console.log("账户持有 DAI 数量:", ethers.utils.formatUnits(daiBalance, 18));

发送交易与写入区块链

当需要发送交易（写入链上数据）时，必须使用 Signer 来签署交易。最基础的例子是转账 Ether。我们可以调用 Signer 的 sendTransaction 方法发起转账交易，指定收款方地址和金额（记得使用 ethers.utils.parseEther() 将 ETH 数额转换为 wei）。该方法返回一个交易对象，我们可以使用 await 等待交易发送完成，并进一步调用 tx.wait() 等待其在链上确认。下面代码演示了使用 Signer 转账 0.1 ETH 的过程：

// 假设 wallet 是一个已连接 Provider 的 Signer 对象（例如 new ethers.Wallet(..., provider)）
const recipientAddress = "0xDEF...";  // 收款人地址
const tx = await wallet.sendTransaction({
    to: recipientAddress,
    value: ethers.utils.parseEther("0.1")  // 转账 0.1 ETH
});
await tx.wait();  // 等待交易被矿工打包确认
console.log("交易已发送，哈希:", tx.hash);

当调用智能合约的状态修改函数时，也需要使用 Signer。可以在创建合约实例时传入 Signer，或使用 contract.connect(signer) 将 Provider 模式的合约实例转换为签名者模式。之后调用例如 await contract.connect(signer).transfer(to, amount) 会返回一个交易对象，与直接使用 Signer 转账类似，需要等待交易确认。

最佳实践

开发者在使用 Ethers.js 时应遵循以下几条最佳实践：

尽量使用测试网络进行开发和调试。例如，可在 Goerli 等测试网部署合约、执行交易，待功能稳定后再切换到主网。
为开发使用单独的测试钱包（也称“burner”钱包），切勿在项目代码或配置中使用存有真实资产的私钥。绝不要将真实资金存入开发测试用的钱包账户。
使用环境变量或配置文件来存放敏感信息（如 Infura API 密钥、私钥等），不要将这些敏感数据硬编码在源码中，也不要将它们提交到代码仓库。
在处理金额数值时，注意以太币的单位换算。善用 ethers.utils.parseEther()、formatEther() 或 formatUnits() 等工具函数来避免精度错误，切勿直接使用浮点数表示 Wei 值。
发送交易后，使用 tx.wait() 等方法等待交易上链确认，确保交易确实被打包成功后再进行后续操作。

易踩的坑

下面是一些初学者在使用 Ethers.js 时常遇到的坑点：

混用 Provider 和 Signer：只有 Signer（带有私钥）才能发送交易或执行链上写操作。如果误将 Provider 当作 Signer 使用（例如调用 provider.sendTransaction），会因缺少签名权限而失败。确保在需要签名的场景下使用正确的 Signer 对象。
忘记使用 await 等待异步结果：Ethers.js 的大部分方法（如读取链上数据、发送交易）都是异步的。如果调用时没有使用 await（或 .then()），将得到一个 Promise 对象，导致后续逻辑出错。例如，忘记 await provider.getBalance() 会导致拿不到实际余额值。
私钥泄漏风险：切勿在前端代码中硬编码私钥，也不要将私钥上传到代码仓库。这会导致严重的安全风险，一旦私钥泄露，攻击者可转移你账户中的所有资产。请使用环境变量管理私钥，并只在可信的后端环境使用它们。
金额单位误差：务必留意 Ether 与 Wei 的单位区别。如果传入交易金额时使用了错误的单位，可能造成金额十万倍的偏差。例如，value: 1 实际发送的是 1 wei（极小的金额），而 ethers.utils.parseEther("1") 才是 1 ETH。

总结

通过以上内容，我们了解到 Ethers.js 提供了简洁而强大的 API 来完成 Web3 开发中的各项操作。从连接节点、交互钱包，到读取合约数据、发送链上交易，Ethers.js 大大降低了与以太坊区块链交互的门槛。掌握了这些基础用法并遵循最佳实践、避开常见陷阱，开发者就能更加自信地使用 Ethers.js 构建出可靠的去中心化应用。