Node.js 一键查询以太坊主币与代币余额的超详细指南

核心关键词：以太坊余额查询、Node.js 区块链开发、Web3 查询 eth、代币余额查询、以太坊地址余额、智能合约 ABI、fromWei 转换、以太坊主网

对于前端开发者，能亲手用 Node.js + Web3 获取链上数据，就像获得了一把打开新世界大门的钥匙。本文将按实战节奏拆解：如何以最少代码快速查询以太坊主币（ETH）与任意 ERC-20 代币余额，并穿插详细示例与可抄作业的完整脚本。

准备工作：三分钟搞定运行环境

Node.js ≥ 14（LTS 系列即可）。
安装依赖
```
npm i web3@latest
```
选定一个 以太坊主网 RPC 节点：
- Alchemy、Infura 都可。
- 把拿到的 https:// 地址存入环境变量 ETH_RPC_URL，方便脚本复用。

👉 点击获取可直接跑通的主网 RPC 节点示例脚本，省去 90% 踩坑时间

查询 ETH 主币余额：两行代码到位

场景回顾

目标：根据 公开钱包地址 拿到该地址持有的 ETH 数量。
单位陷阱：链上原生单位为 wei，需要转换成人类可读的 ether。

代码展示

const Web3 = require('web3');
const web3 = new Web3(process.env.ETH_RPC_URL);

async function getETHBalance(wallet) {
  let wei = await web3.eth.getBalance(wallet);        // 返回 BigInt 串
  let eth = web3.utils.fromWei(wei, 'ether');         // 转换为 ether
  console.log(`地址 ${wallet} 持有 ${eth} ETH`);
  return eth;
}

// 调用示例
getETHBalance('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');

关键点速记

web3.eth.getBalance：单次请求 ≈ 节点延迟，无需额外授权。
fromWei：是照顾人类阅读体验的核心函数，千万别忘掉。

查询 ERC-20 代币余额：五步法必胜

场景回顾

使用 代币合约地址 + 钱包地址 查询余额。
需要 ABI（Application Binary Interface） 才能与合约对话。

STEP-1：准备 ABI

最精简的 ERC-20 ABI 只需包含四个方法名：

[
  {"constant":true,"inputs":[],"name":"name","outputs":[{"name":"","type":"string"}],"type":"function"},
  {"constant":true,"inputs":[],"name":"symbol","outputs":[{"name":"","type":"string"}],"type":"function"},
  {"constant":true,"inputs":[],"name":"decimals","outputs":[{"name":"","type":"uint8"}],"type":"function"},
  {"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"balanceOf","outputs":[{"name":"","type":"uint256"}],"type":"function"}
]

用 记事本保存为 abi.json 即可，约 500 字节。

STEP-2：封装通用查询函数

const fs = require('fs');
const abi = JSON.parse(fs.readFileSync('./abi.json', 'utf8'));

async function getTokenBalance(wallet, contractAddr) {
  const contract = new web3.eth.Contract(abi, contractAddr);

  const [name, symbol, decimals, balanceWei] = await Promise.all([
    contract.methods.name().call(),
    contract.methods.symbol().call(),
    contract.methods.decimals().call(),
    contract.methods.balanceOf(wallet).call()
  ]);

  const balance = balanceWei / (10 ** decimals);  // 手动计算更直观
  console.log(`${wallet} 持有 ${balance} ${symbol}（${name}）`);
  return { name, symbol, balance };
}

STEP-3：实战演练

拿 USDT 合约地址（0xdAC17F958D2ee523a2206206994597C13D831ec7）测一下：

getTokenBalance('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
                '0xdAC17F958D2ee523a2206206994597C13D831ec7');

输出示例：

0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 持有 123.456 USDT

👉 解锁完整工程模板：让团队在 1 小时内批跑上百个地址的余额抓取

真实项目技巧：把请求包一层缓存

RPC 限速：主网节点常见 10 req/sec 限制，大规模查询务必加 promise-pool。
本地缓存：可把高频地址写入 Redis，10 分钟刷新一次。
日志保留：失败地址集中输出，方便后续手动补抓，提升运维体验。

常见问题 FAQ

阅读前先扫一眼，也许你的困惑就在这里。

Q1：查询结果总是 0，是哪里错了？
A：99% 发生在 合约地址写错 或 钱包地址大小写没转 checksum。用 web3.utils.toChecksumAddress 再做一次标准化即可。

Q2：远程 RPC 调用超时怎么办？
A：换节点，或把单次并发降到 3 个以内。节点服务商对不同套餐的 QPS 限制差异极大。

Q3：fromWei 和手动除法，两者优劣？
A：fromWei 内部已封装 BigNumber 精度，直接用它最简单。手动除法需保证 decimals 正确，否则容易算成科学计数法。

Q4：主网与测试脚本能共用吗？
A：只要把 ETH_RPC_URL 换成测试网（Goerli、Sepolia 等）即可。同一接口，一行环境变量就搞定。

Q5：如何一次查询多个代币？
A：把合约地址数组化，用 Promise.all 并行请求。务必加并发限制。

结语：把脚本镶嵌到业务流程

定时任务：每 5 分钟采集热点地址余额，存进数据库，制作实时面板。
前端对接：配合 ethers.js 或 wagmi，在前端页面实时展示用户资产。
监管工具：批量核查大量钱包的 ETH 及代币持有量，节省人工对账时间。

拿到本文代码，你就能以 极简脚本 把 以太坊余额查询 嵌入 Node.js 管道，开发效率直线上扬。祝你项目一路绿灯！