智能合约与以太坊 / 系统课时
用 ethers v6 读取合约状态
用 ethers v6 读取合约状态
DApp 显示代币余额、计数器数值或合约配置时,需要通过 RPC 调用链上的只读函数。本课使用 ethers v6 创建 BrowserProvider 和 Contract,以 Ethereum 主网 USDC 合约为例,完成钱包连接、ABI 调用、bigint 处理和页面显示,并验证整个读取过程不发送交易。
学习目标
- 使用浏览器注入的钱包创建 BrowserProvider,并区分 Provider 与 Signer 的职责。
- 使用最小 ABI 创建 Contract,调用 view 函数读取链上状态。
- 正确处理 uint256 返回的 bigint,通过 formatUnits 转换为可显示的余额。
准备浏览器环境与合约 ABI
本例使用 JavaScript、Vite、ethers v6 和支持 EIP-1193 的浏览器钱包。需要提前安装 Node.js、npm 和浏览器钱包,并将钱包切换到 Ethereum 主网。只读取余额,不需要账户持有 ETH,也不需要准备 USDC。
在终端创建一个 Vanilla JavaScript 项目:
npm create vite@latest ethers-read-demo -- --template vanilla
cd ethers-read-demo
npm install
npm install ethers@6
npm run dev预期结果:Vite 启动本地开发服务器,终端显示类似下面的地址,实际端口可能不同。
Local: http://localhost:<PORT>/使用浏览器打开终端显示的地址。后续修改 src/main.js,Vite 会自动更新页面。
本例选用 Ethereum 主网原生 USDC 合约,地址为 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48。USDC 使用 6 位小数,因此不能直接按 ETH 的 18 位小数格式化余额。
ABI 是前端理解合约函数签名、输入参数和返回值的描述。读取 USDC 余额只需以下三个函数,不必导入完整合约 ABI。
| 函数 | 参数 | 返回类型 | 用途 |
|---|---|---|---|
balanceOf(address) |
账户地址 | uint256 |
查询最小单位余额 |
decimals() |
无 | uint8 |
查询代币小数位数 |
symbol() |
无 | string |
查询代币符号 |
这些都是只读函数。ethers 会使用 ABI 编码调用数据,再通过 RPC 发起 eth_call,最后根据 ABI 解码返回值。
创建 BrowserProvider 并完成只读调用
BrowserProvider 用来包装钱包注入的 window.ethereum 对象。它负责将 ethers 的读取请求交给钱包提供的 EIP-1193 接口。
Contract 接收三个参数:合约地址、ABI 和执行调用的 Provider。本例将 Provider 作为第三个参数,所以可以读取状态,但不需要获取 Signer。

将 src/main.js 的内容替换为下面的完整示例:
import { BrowserProvider, Contract, formatUnits } from "ethers";
const USDC_ADDRESS = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
const ABI = [
"function balanceOf(address account) view returns (uint256)",
"function decimals() view returns (uint8)",
"function symbol() view returns (string)"
];
const app = document.querySelector("#app");
app.innerHTML = `
<h1>USDC 余额查询</h1>
<button id="read">连接钱包并读取余额</button>
<pre id="result">尚未读取</pre>
`;
const result = document.querySelector("#result");
document.querySelector("#read").addEventListener("click", async () => {
if (!window.ethereum) {
result.textContent = "未检测到浏览器钱包";
return;
}
result.textContent = "正在读取...";
try {
const provider = new BrowserProvider(window.ethereum);
const network = await provider.getNetwork();
// 示例地址属于主网,先阻止错误网络上的合约调用。
if (network.chainId !== 1n) {
result.textContent = "请切换到 Ethereum 主网后重新读取";
return;
}
// 申请查看当前钱包账户,读取合约本身不需要签名。
const accounts = await provider.send("eth_requestAccounts", []);
if (accounts.length === 0) {
throw new Error("钱包没有返回账户地址");
}
const account = accounts[0];
const contract = new Contract(USDC_ADDRESS, ABI, provider);
// 并发读取三个独立的 view 函数。
const [rawBalance, decimals, symbol] = await Promise.all([
contract.balanceOf(account),
contract.decimals(),
contract.symbol()
]);
const balance = formatUnits(rawBalance, decimals);
result.textContent =
`账户:${account}\n` +
`原始余额:${rawBalance.toString()}\n` +
`显示余额:${balance} ${symbol}`;
} catch (error) {
result.textContent = `读取失败:${error.shortMessage ?? error.message}`;
}
});保存文件后,在浏览器点击“连接钱包并读取余额”。首次连接时,钱包可能弹出账户访问授权窗口。允许访问后,页面查询该账户的 USDC 余额。
这里有两个容易混淆的操作:
eth_requestAccounts:请求用户授权 DApp 查看账户地址,钱包可能弹窗,但这不是链上交易。contract.balanceOf(account):经由 Provider 发出只读调用,RPC 查询合约状态并返回编码结果,不要求钱包签署交易。
provider.getSigner() 主要用于需要账户签名的操作;读取公开合约状态时并非必要。实际 DApp 也可以直接查询一个已知地址的余额,从而完全跳过账户授权步骤。
验证读取结果与 bigint 格式化
页面读取成功后,应显示账户地址、原始余额和格式化余额。如果当前账户的 USDC 余额为零,预期结果类似:
账户:<ID>
原始余额:0
显示余额:0.0 USDC其中 <ID> 表示实际钱包地址。对于非零余额,原始余额与显示余额取决于链上实时状态,不应预设固定数值。
ethers v6 将 Solidity 的 uint256 等整数返回值解码为 JavaScript bigint。例如原始余额为 123456789n,USDC 小数位为 6,则显示余额应为 123.456789。
可以使用以下独立代码验证格式化规则:
import { formatUnits } from "ethers";
const rawBalance = 123456789n;
const decimals = 6n;
// 保持原始值为 bigint,仅在显示时转成十进制字符串。
console.log(typeof rawBalance);
console.log(rawBalance.toString());
console.log(formatUnits(rawBalance, decimals));预期输出:
bigint
123456789
123.456789formatUnits 返回字符串,不是浮点数。业务代码应保留 bigint 参与整数运算,在 UI 显示时再做单位转换,这样可以避免大整数精度损失。
需要注意以下边界:
- 不要直接执行
Number(rawBalance):超过 JavaScript 安全整数范围时可能丢失精度。 - 不要直接使用
JSON.stringify(rawBalance):原生 JSON 不支持bigint,需要先调用toString()。 - 不要固定使用
formatEther()处理代币余额:该函数按 18 位小数解释数值,USDC 实际使用 6 位。应优先读取合约的decimals()。 - 不要把显示字符串当成精确计算值:需要进行代币金额运算时,应继续使用原始整数,必要时通过
parseUnits()转换输入。
例如,若将 123456789 个 USDC 最小单位错误地按 18 位小数转换,结果会变为 0.000000000123456789,与真实的 123.456789 USDC 相差巨大。
排查网络、ABI 与钱包读取异常
如果按钮点击后没有得到余额,应按照从环境到合约的顺序定位,不要先怀疑 formatUnits()。
| 现象 | 常见原因 | 检查与修复 |
|---|---|---|
| 未检测到浏览器钱包 | 没有注入 window.ethereum |
确认已安装并启用兼容钱包,刷新页面 |
| 钱包授权被拒绝 | 用户拒绝账户访问请求 | 重新点击按钮,在钱包中允许连接 |
| 提示切换 Ethereum 主网 | 当前 chainId 不是 1 | 手动切换到 Ethereum Mainnet,再点击读取 |
BAD_DATA 或无法解码 |
地址无合约代码、网络错误或 ABI 不匹配 | 检查合约地址、chainId 和函数返回类型 |
CALL_EXCEPTION |
合约调用执行失败 | 检查参数、函数是否存在及合约是否回滚 |
| RPC 超时或请求限流 | 钱包 RPC 不可用或请求过于频繁 | 检查网络连接、切换可靠 RPC、降低查询频率 |
| 余额为零 | 该账户没有 USDC | 检查账户是否正确,并与区块浏览器查询结果对照 |
还要注意:钱包在页面打开后可能发生账户或网络切换。本例是点击按钮时读取一次的最小实现,因此切换账户或网络后必须重新点击查询。正式应用应监听 EIP-1193 的 accountsChanged、chainChanged 事件,在变化时更新账户状态、重新检查网络并刷新查询结果。
完成验证后,可以将本例的 USDC 地址替换为自己部署的合约地址,同时把 ABI 改成合约实际暴露的只读函数。务必让 Provider 所连接的网络与合约部署网络一致,并让 ABI 的函数名称、参数和返回类型与链上实现匹配。更多 API 细节可参考 ethers v6 官方文档。