web3.js web3-utils 实用工具包全解析:从 4.x 版本演进看以太坊开发工具链的底层能力

原创2026-09-20 11:27:221,814 阅读
文章标签:区块链Web3

web3.js web3-utils 实用工具包全解析:从 4.x 版本演进看以太坊开发工具链的底层能力

web3-utils 是 web3.js 生态中面向 DApp 开发者的通用工具子包,承担着数值与单位换算、哈希计算、类型校验、JSON-RPC 载荷构造、Socket 连接管理等基础职责。本文以仓库内 packages/web3-utils/CHANGELOG.md 的版本记录为主线骨架,结合 packages/web3-utils/src 目录下的真实源码实现,系统梳理 web3-utils 从 4.0.1-alpha 到 4.3.3 的能力演进、关键函数用法与底层原理,帮助你在使用 web3.utils 或独立安装 web3-utils 时,准确理解每个工具函数的行为与边界。

一、包定位与接入方式

根据 packages/web3-utils/README.md 的定义,web3-utils 是 web3.js 的子包,包含 DApp 开发者常用的实用函数。当前仓库中该包版本为 4.3.3(见 packages/web3-utils/package.json),支持 Node.js >= 14,并采用 LGPL-3.0 协议。

两种典型接入方式:

# 方式一:随主包使用(推荐在完整 web3 场景下)
npm install web3
# 或 yarn add web3

# 方式二:独立安装,构建轻量应用(tree-shaking 友好)
npm install web3-utils
# 或 yarn add web3-utils

方式一的用法(通过 web3.utils 命名空间):

import { Web3 } from 'web3';

const web3 = new Web3();
const value = web3.utils.fromWei('1', 'ether'); // "0.000000000000000001"

方式二的用法(按需导入,更利于减小打包体积):

import { fromWei, soliditySha3Raw } from 'web3-utils';

console.log(fromWei('1', 'ether'));
console.log(soliditySha3Raw({ type: 'string', value: 'helloworld' }));

从源码看,包的导出面非常全面。packages/web3-utils/src/index.ts 统一导出了 converters(转换器)、event_emitter(事件发射器)、validation(校验)、formatter(格式化)、hash(哈希)、random(随机数)、string_manipulation(字符串操作)、objects(对象工具)、promise_helpers(Promise 工具)、json_rpc(JSON-RPC 工具)、web3_deferred_promise、chunk_response_parser、uuid、web3_eip1193_provider、socket_provider、uint8array 等多个模块,并为了兼容 1.x 额外导出了 AbiItem 类型(源自 web3-types)。

二、异步与轮询利器:promise_helpers 模块

CHANGELOG 在 4.0.1-alpha.1 中记录了最早引入的一组 Promise 工具函数:pollTillDefined、rejectIfTimeout、rejectIfConditionAtInterval,官方描述是"在处理涉及轮询、超时拒绝或按时间间隔重复检查条件是否满足的 Promise 时非常有用"。

2.1 轮询直到有结果:pollTillDefined

pollTillDefined 会按给定间隔反复调用一个异步函数,直到返回值非 undefined/null,或超时为止。其底层实现在 packages/web3-utils/src/promise_helpers.ts:

export async function pollTillDefined<T>(
	func: AsyncFunction<T>,
	interval: number,
): Promise<Exclude<T, undefined>> {
	return pollTillDefinedAndReturnIntervalId(func, interval)[0];
}

其中 AsyncFunction<T, K = unknown> 是 (...args: K[]) => Promise<T> 的类型别名。真正完成轮询的是 pollTillDefinedAndReturnIntervalId,它返回 [Promise<Exclude<T, undefined>>, Timer] 二元组——前者是最终结果 Promise,后者是 setInterval 返回的定时器 ID。轮询循环内部每次调用都会经过 waitWithTimeout(func, interval) 包裹:当某次调用返回非空值(isNullish(res) 为假)时,立即 clearInterval 并 resolve;若调用抛出异常,则清空定时器并 reject。

两点实践建议:

  • 如果不需要拿到 intervalId,直接使用 pollTillDefined 即可;源码注释明确提示它"将在下一个大版本中废弃",推荐使用能同时返回 IntervalId 的 pollTillDefinedAndReturnIntervalId。
  • 典型场景是等待交易收据、等待 ENS 解析结果、等待节点同步到某个区块号等"轮询直到有确定答案"的需求。

2.2 超时强制拒绝:rejectIfTimeout

rejectIfTimeout(timeout, error) 返回 [Timer, Promise<never>],其中 Promise 会在 timeout 毫秒后以指定 error reject。源码实现非常直接:

export function rejectIfTimeout(timeout: number, error: Error): [Timer, Promise<never>] {
	let timeoutId: Timer | undefined;
	const rejectOnTimeout = new Promise<never>((_, reject) => {
		timeoutId = setTimeout(() => {
			reject(error);
		}, timeout);
	});
	return [timeoutId!, rejectOnTimeout];
}

使用示例(源码 JSDoc 中的例子):

const [timerId, promise] = web3.utils.rejectIfTimeout(100, new Error('time out'));

将返回的 Promise 与其他 Promise 一起放入 Promise.race,即可实现"超时即失败"的竞速控制;拿到 timerId 后记得在分支结束时 clearTimeout,避免定时器泄漏。

2.3 条件触发拒绝:rejectIfConditionAtInterval

rejectIfConditionAtInterval(cond, interval) 会按 interval 间隔重复执行条件函数 cond,一旦 cond 返回了非空值(视为错误对象),立即清除定时器并以该值 reject。它返回 [Timer, Promise<never>]。适合实现"心跳检测失败即断开""余额低于阈值即告警"这类主动监控逻辑。

2.4 配套基础函数:waitWithTimeout 与 isPromise

  • waitWithTimeout(awaitable, timeout, error?):等待一个 Promise(或会被调用的异步函数),若在 timeout 内未完成,则抛出传入的 error;未传 error 时返回 undefined。实现上利用 Promise.race,并在结束后 clearTimeout。
  • isPromise(object):4.0.1-alpha.2 新增,替代 Node 环境才有、浏览器不可用的 util/types.isPromise。判定逻辑为:对象是 object 或 function,且拥有 then 函数(见 packages/web3-utils/src/promise_helpers.ts)。

这些函数的正确性有单元测试保障,测试位于 packages/web3-utils/test/unit/promise_helpers.test.ts。

三、UUID 与 JSON-RPC ID:uuid 与 json_rpc 模块

4.0.1-alpha.2 引入了 uuidV4 函数,并同步修复了一个重要问题:"Responses get mixed up due to conflicting payload IDs"(响应因冲突的载荷 ID 而混淆)。这正是 JSON-RPC 请求 id 唯一性问题的根源。

3.1 uuidV4:随机版本 4 UUID

packages/web3-utils/src/uuid.ts 中 uuidV4 的实现思路:先调用 randomBytes(16)(源自 packages/web3-utils/src/random.ts,其内部委托 ethereum-cryptography 的 getRandomBytesSync),再按照 RFC 4122 设置版本位与变体位:

bytes[6] = (bytes[6] & 0x0f) | 0x40; // 版本 4
bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 变体

最终把 16 字节的十六进制串按 8-4-4-4-12 的格式用 - 拼接,形如 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed。

3.2 setRequestIdStart 与 toPayload:可控的请求 ID

packages/web3-utils/src/json_rpc.ts 中的 setRequestIdStart(start) 允许传入起始数字,让后续 JSON-RPC 请求的 id 从该数字开始递增;传入 undefined 则回退到 UUID 模式(默认行为)。toPayload 在构造请求载荷时按 request.id ?? requestIdSeed ?? uuidV4() 的优先级取值——这意味着你既可以完全自定义 ID,也可以用 setRequestIdStart 得到可预测的自增数字 ID,或者依赖默认的 UUID 保证全局唯一性。

同文件还提供了一组响应判定工具:isResponseWithResult、isResponseWithError、isResponseWithNotification、isSubscriptionResult、isValidResponse、isBatchResponse 等,用于区分 JSON-RPC 2.0 响应、通知与订阅推送消息。

四、数值与单位转换:converters 模块的核心函数

CHANGELOG 中有大量条目围绕数值转换展开,这些函数集中在 packages/web3-utils/src/converters.ts,也是开发中最高频使用的一批 API。

4.1 numberToHex 与 hexstrict 参数(4.0.1-rc.2 新增)

numberToHex(value, hexstrict?) 将数值转十六进制。当 hexstrict 为 true 时,若结果长度为奇数会在前面补 0,保证严格的字节对齐(奇数长度的 hex 串按字节读取会有歧义)。实现上复用 web3-validator 的 numberToHex,再针对正负奇数长度做 '0x0' / '-0x0' 前缀修正。4.0.3 修复了 BigInt 输入在 numberToHex 中通过校验的问题——因此现在传 BigInt 也不会被误拦截。

4.2 toNumber 与 toBigInt:大数安全(4.2.2 / 4.2.3 修复)

toNumber(value) 的返回类型是 number | bigint:

  • 输入为 number 时,若大于 1e20 会打印精度丢失警告并返回 BigInt,因为 JavaScript 将大于等于 10^21 的数字转字符串时会变成科学计数法(如 String(10000000000000000000000) 得到 '1e+22'),导致后续解析错误;
  • 输入为 bigint 时,仅在 [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER] 范围内转换为 number,否则原样返回 bigint;
  • 输入为 hex 字符串时走 hexToNumber。

4.2.2 的"修复 toNumber 对大数的错误解析"、4.2.3 的"修复 toHex 对 Uint8Array/Buffer 的错误十六进制化"均落在这条逻辑线上。toBigInt(value) 则统一将 number/bigint/数字字符串(含负号)转换为 bigint。

4.3 toWei / fromWei:单位换算与精度警告(4.3.0 系列)

toWei(number, unit) 与 fromWei(number, unit) 负责以太坊单位与 wei 之间的换算。单位表 ethUnitMap 定义在 converters.ts 顶部(@internal),覆盖从 noether、wei、kwei/Kwei/babbage/femtoether、mwei/Mwei/lovelace/picoether、gwei/Gwei/shannon/nanoether/nano、szabo/microether/micro、finney/milliether/milli、ether 到 kether/grand、mether、gether、tether 的全量别名,全部以 BigInt 存储倍率。

4.3.0 的重要行为变更:

  • 单位参数支持整数,即把单位直接当作 10 的幂次处理(bigintPower(BigInt(10), BigInt(unit))),例如 toWei('1', 6) 等价于 mwei;
  • 当传入 number 类型且数值过大(> 1e20)或过小(< 1e-15)时,会打印 PrecisionLossWarning 提示使用 string 或 BigInt 避免精度丢失;
  • 支持科学计数法输入;
  • 按单位正确修剪小数尾部零。

4.3.3 修复了 fromWei 在输入为 0 时返回 "0" 而不是 "0.0" 的问题。注意 fromWei 总是返回字符串,toWei 亦然,这是为了不丢失大数精度。

4.4 字节与 hex 互转(4.0.1-rc.2 的 Buffer → Uint8Array 迁移)

4.0.1-rc.2 是一次影响面很大的破坏性变更:全包用 Uint8Array 取代 Buffer。hexToBytes、randomBytes 不再返回 Buffer 而返回 Uint8Array;sha3、keccak256Wrapper 不再接受 Buffer 输入;bytesToBuffer 被移除,统一使用 bytesToUint8Array。4.2.3 又修复了 isUint8Array 对 Buffer 返回 false 的问题,保证浏览器与 Node 环境下行为一致。

常用互转函数速览(均带示例输出,见源码 JSDoc):

函数 作用 示例
bytesToUint8Array 任意字节表示转 Uint8Array "0xab" → Uint8Array(1) [171]
bytesToHex 字节数组转 hex Uint8Array([72, 12]) → "0x480c"
hexToBytes hex 转字节数组(自动补 0x) '0x74657374' → Uint8Array(4) [116, 101, 115, 116]
hexToNumber / toDecimal hex 转 number/bigint '0xa' → 10
numberToHex / fromDecimal 数值转 hex 10 → "0xa"
utf8ToHex / fromUtf8 / stringToHex UTF-8 字符串转 hex 'web3.js' → "0x776562332e6a73"
hexToUtf8 / toUtf8 / hexToString hex 转 UTF-8 字符串 '0x48656c6c6f20576f726c64' → "Hello World"
asciiToHex / fromAscii ASCII 转 hex 'Hello World' → "0x48656c6c6f20576f726c64"
hexToAscii / toAscii hex 转 ASCII 同上反向
toHex 智能推断类型并转 hex(可返回类型) toHex(10) → "0xa"

其中 toHex 是"自动转换器":对地址返回小写 0x 形式,对布尔返回 0x01/0x00,对数字/大整数走 numberToHex,对 Uint8Array 走 bytesToHex,对普通对象则先 JSON.stringify 再按 UTF-8 编码——这也是 1.x 用户最熟悉的语义。需要注意 toHex 无法处理时抛出 HexProcessingError。

五、哈希与签名数据:hash 模块

packages/web3-utils/src/hash.ts 提供以太坊生态最常用的哈希工具。

5.1 sha3 与 keccak256Wrapper

keccak256Wrapper 是 ethereum-cryptography/keccak256 的包装器,扩展了输入类型:支持 string、number、bigint、字节数组。对数字/大整数会先转成十进制字符串再 UTF-8 编码(如 keccak256Wrapper(1) 计算的是字符串 "1" 的哈希),对非严格 hex 的字符串按 UTF-8 处理,否则按字节处理。

sha3(data) 在 keccak256Wrapper 之上增加了一层 EIP-1052 语义:当哈希结果等于空数据的 Keccak-256 值 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470(即 SHA3_EMPTY_BYTES 常量)时返回 undefined。例如:

console.log(web3.utils.sha3('web3.js'));
// > 0x63667efb1961039c9bb0d6ea7a5abdd223a3aca7daa5044ad894226e1f83919a

console.log(web3.utils.sha3(''));
// > undefined

若你希望空输入也返回固定哈希值而非 undefined,应使用 sha3Raw。CHANGELOG 中 4.0.6 记录的"soliditySha3() 支持 BigInt"也位于本模块——soliditySha3 系列负责按 Solidity 类型(如 { type: 'string', value: '...' } 或 { t: 'uint256', v: 1n })编码参数后计算 Keccak-256,是构造 keccak256(abi.encodePacked(...)) 式哈希的便捷入口。

5.2 相关字符串工具:padLeft / padRight

4.3.2 修复了 padRight 在大型 uint 上的校验失败问题。这类填充函数(padLeft、padRight、toTwosComplement、fromTwosComplement)位于 packages/web3-utils/src/string_manipulation.ts,在 ABI 编码与格式化流程中被广泛依赖。

六、格式化输出:formatter 模块与 DataFormat

4.0.1-rc.1 将 FMT_NUMBER、NumberTypes、FMT_BYTES、ByteTypes、DataFormat、DEFAULT_RETURN_FORMAT、ETH_DATA_FORMAT、FormatType 等类型迁移到了 web3-types(见 packages/web3-types/src/data_format_types.ts),web3-utils 侧保留运行时的格式化能力。

4.2.3 变更:format 方法的 returnFormat 参数现在有默认值 DEFAULT_RETURN_FORMAT,即调用方可以省略该参数。

packages/web3-utils/src/formatter.ts 的核心是 convertScalarValue(value, ethType, format),它根据以太坊类型和输出格式做转换:

  • int/uint 类型依据 format.number 在四种模式间切换:FMT_NUMBER.NUMBER(number)、FMT_NUMBER.HEX(hex 字符串)、FMT_NUMBER.STR(十进制字符串)、FMT_NUMBER.BIGINT(bigint);
  • bytes 类型依据 format.bytes 在 FMT_BYTES.HEX 与 FMT_BYTES.UINT8ARRAY 之间切换,固定长度字节还会做 padLeft / uint8ArrayConcat 补齐。

理解这套 DataFormat 机制,就能掌控 web3.eth.getBalance(addr) 等调用返回的是 number、bigint、hex 字符串还是 Uint8Array——这是从 1.x 迁移到 4.x 时最需要适应的行为差异之一(对应官方 Migration Guide 中 web3-utils 一节的内容)。

七、网络层能力:SocketProvider 与事件系统

7.1 SocketProvider 的队列管理(4.1.0 新增)

CHANGELOG 4.1.0 为 SocketProvider 增加了四个公开方法(实现于 packages/web3-utils/src/socket_provider.ts):

  • getPendingRequestQueueSize():返回等待中的请求队列大小(第 196 行);
  • getSentRequestsQueueSize():返回已发送但未确认的请求队列大小(第 205 行);
  • clearQueues(event?):清空两类队列;
  • safeDisconnect(code?, data?, forceDisconnect = false, ms = 1000):仅在请求队列与已发送队列均为 0 时才安全断开;forceDisconnect 为 true 或超过 ms 毫秒后仍强制断开。

这套 API 解决了 WebSocket 提供者在有未完成请求时直接断开导致响应丢失的竞态问题——safeDisconnect 的语义就是"确认没有在途请求后再断链"。

7.2 更早的基础设施变更

  • 4.0.1-alpha.4:新增 SocketProvider 类与 Eip1193Provider 抽象类;
  • 4.0.1-rc.0:SocketProvider 改为 resolve JSON-RPC 响应错误而非 reject,且暴露了 SocketConnection 的 getter;
  • 4.3.1:_sendPendingRequests 会捕获来自 _sendToSocket 的未处理错误。

7.3 EventEmitter 的演进(4.0.7 / 4.2.1)

4.0.7 实现了并导出自定义 EventEmitter 以替代 Node 的 EventEmitter(解决浏览器环境兼容);4.2.1 又将其替换为 eventemitter3,以支持 React Native 构建。当前 packages/web3-utils/package.json 的依赖中可以看到 eventemitter3: ^5.0.1。4.0.7 同时修复了 Babel/React 默认配置下的 BigInt 报错("TypeError: Cannot convert a BigInt value to a number")以及块处理逻辑(chunks processing)的 bug。

八、其他值得关注的能力

  • 随机数(4.0.1-rc.2 起返回 Uint8Array):packages/web3-utils/src/random.ts 提供 randomBytes(size) 与 randomHex(byteSize),底层委托 ethereum-cryptography 的 getRandomBytesSync。
  • 区块标签比较(4.0.1-rc.0):compareBlockNumbers 移除了 genesis 标签支持,新增 safe 与 finalized 标签;4.0.1-rc.1 之后该函数仅支持"两个区块标签参数"(除 earliest 与数字的组合外)或"两个区块号参数"的比较。
  • 兼容性导出(4.2.0):补回 1.x 中存在的 AbiItem 类型导出,降低迁移成本。
  • 构建产物(4.0.1-rc.1):源码文件纳入发布包,并提供 ESM 与 CJS 混合构建;tsc 编译产物从 dist/ 移入 lib/(对应 lib/esm、lib/commonjs、lib/types 三套产物,见 packages/web3-utils/package.json 的 exports 与 build:cjs/build:esm/build:types 脚本)。4.0.1-rc.1 还移除了对 @ethereumjs/tx、@ethereumjs/common 的依赖,4.3.3 将 TypeScript 从 4.x 升级到 5.x。

九、版本演进时间线速查

版本 关键变更摘要
4.0.1-alpha.1 新增 pollTillDefined、rejectIfTimeout、rejectIfConditionAtInterval
4.0.1-alpha.2 新增 uuidV4、isPromise;JSON-RPC 响应 ID 改用 UUID 修复载荷混淆
4.0.1-rc.0 compareBlockNumbers 支持 safe/finalized,移除 genesis;SocketProvider resolve 错误
4.0.1-rc.1 新增混合构建;格式化类型迁移至 web3-types
4.0.1-rc.2 numberToHex 增加 hexstrict;全包 Buffer → Uint8Array 迁移
4.0.3 numberToHex 支持 BigInt 校验
4.0.6 soliditySha3() 支持 BigInt
4.0.7 自定义 EventEmitter;修复 BigInt 转 number 报错
4.1.0 SocketProvider 队列管理 API 与 safeDisconnect;isContractInitOptions
4.2.0 补回 AbiItem 类型导出
4.2.1 换用 eventemitter3 支持 React Native
4.2.2 修复 toNumber 大数解析
4.2.3 format 的 returnFormat 默认 DEFAULT_RETURN_FORMAT;修复 toHex/isUint8Array
4.3.0 toWei/fromWei 支持整数单位、精度警告、科学计数法
4.3.1 _sendPendingRequests 捕获 socket 未处理错误
4.3.2 修复 padRight 大 uint 校验失败
4.3.3 fromWei('0') 返回 "0";TypeScript 升级到 5.x

十、最佳实践小结

  1. 大数一律用 string 或 bigint:toWei/fromWei 在传入 number 且超过 1e20 或低于 1e-15 时会告警,务必用字符串承载金额,最终结果也是字符串。
  2. 优先使用 Uint8Array 而非 Buffer:4.0.1-rc.2 起所有字节 API 统一为 Uint8Array,跨浏览器与 Node 行为一致。
  3. 请求 ID 冲突时用 UUID 或自增种子:默认 toPayload 使用 uuidV4() 生成唯一 ID;需要可预测 ID 时调用 setRequestIdStart(n)。
  4. 轮询/超时场景复用 promise_helpers:与其手写 setInterval + setTimeout 组合,不如直接使用 pollTillDefinedAndReturnIntervalId、waitWithTimeout、rejectIfTimeout 等经过测试的基础件。
  5. 理解 DataFormat 决定返回值形态:number、bigint、hex 字符串与 Uint8Array 的选择由 FMT_NUMBER/FMT_BYTES 组合决定,格式化细节见 packages/web3-utils/src/formatter.ts。
  6. Socket 场景善用 safeDisconnect:先确认请求队列为空再断开,避免在途请求响应丢失。

web3-utils 的价值在于"小而稳":每个函数都承担了明确的边界处理(大数精度、字节格式、类型推断、异步时序),而这些细节正是以太坊开发中最容易踩坑的地方。阅读 packages/web3-utils/CHANGELOG.md 与 packages/web3-utils/src 源码,是快速掌握这些边界条件的最佳途径。

登录后查看全文
web3.js