从 1.x 到 4.xweb3.js 工具函数库web3-utils完整迁移指南【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js导读web3.js 4.x 对工具函数库web3-utils做了一系列破坏性变更推荐按需命名导入、用原生BigInt取代BN、强制显式传入单位参数、调整toHex/isHex的边界行为、把校验函数迁移到web3-validator、把stripHexPrefix挪到web3-eth-accounts并收紧了compareBlockNumbers的类型约束。本文以官方迁移指南为骨架结合仓库源码与测试用例逐项拆解这些差异给出可直接复制的迁移示例帮助你将基于 web3.js 1.x 的代码平滑升级到 4.x。迁移总览一次看清所有破坏性变更变更项1.x 行为4.x 行为影响等级导入方式import web3Utils from web3-utils推荐import * as web3Utils from web3-utils或按需命名导入编译期BN大数类内置Web3.utils.BN基于 bn.js移除改用原生BigInt运行时toWei单位参数可省略默认ether必须显式传入单位编译期/运行时toHex(1)数字字符串被当作数字返回0x1纯数字字符串按字符串处理返回0x31运行时易踩坑校验函数位于web3-utils迁移至web3-validator旧位置标记 deprecated编译期告警stripHexPrefix位于web3-utils迁移至web3-eth-accounts编译期compareBlockNumbers允许 block tag 与数字混比只允许同类比较或earliest特例否则抛InvalidBlockError运行时其中大部分为编译期即可发现的变化真正需要逐行排查的是toHex的字符串语义变化与compareBlockNumbers的抛错行为——这两处属于编译能过、运行结果不同/抛错的隐蔽差异。导入方式按需命名导入1.x 中web3-utils默认导出整个工具包4.x 将每个工具函数改为具名导出见 packages/web3-utils/src/index.ts 中从converters.js、validation.js、hash.js、random.js等模块的export *转发并鼓励只导入应用实际用到的函数以利于 tree-shaking 减小打包体积// 1.x —— 默认导出整个包 import web3Utils from web3-utils; // 4.x —— 全量导入兼容 1.x 习惯 import * as web3Utils from web3-utils; // 4.x —— 推荐按需具名导入 import { toWei, fromWei, toHex } from web3-utils;该改动不影响Web3.utils与web3.utils命名空间的访问方式例如web3.utils.toWei(0.1, ether)依然可用。按需导入配合 4.x 的 tree-shaking 支持能显著减小最终 bundle 体积可参考 13_advanced/tree_shaking 一节。告别 BN全面切换原生 BigInt1.x 中web3-utils内置BN属性封装 bn.js用于处理超出Number安全范围的大整数。4.x 移除了该属性全面采用 JavaScript 原生BigInt类型// 1.x new Web3.utils.BN(1); // 4.x BigInt(4);这一变更的底层证据在源码中随处可见单位换算映射表ethUnitMap的全部值均为BigInt见 packages/web3-utils/src/converters.ts 中wei: BigInt(1)、ether: BigInt(1000000000000000000)等compareBlockNumbers在数字比较路径上直接使用BigInt(blockA) BigInt(blockB)进行比较见 packages/web3-utils/src/validation.ts。迁移时注意BigInt与Number不能直接混用算术运算符跨类型计算需显式转换另外BigInt不能与Math.*函数、JSON 序列化直接配合需要时可用Number(...)或toString()过渡。单位换算toWei/fromWei 必须显式传单位1.x 中toWei的第二参单位可省略默认ether。4.x 中该可选参数被移除必须显式传入单位// 1.x —— 省略单位默认 ether web3.utils.toWei(0.1); // 4.x —— 必须显式传单位 web3.utils.toWei(0.1, ether);从 packages/web3-utils/src/converters.ts 的toWei实现可以看到单位参数unit: EtherUnits | number已被声明为必选且支持两类取值字符串单位查表ethUnitMap如wei、gwei、shannon、ether等传入不存在的单位会抛InvalidUnitError数字十进制幂直接作为 10 的指数例如传18等价于etherdenomination bigintPower(BigInt(10), BigInt(18))。fromWei同样要求显式单位见 packages/web3-utils/src/converters.ts。此外当以number类型传入较大数值或高精度小数时库会输出PrecisionLossWarning警告提示改用string或BigInt以避免精度丢失——这是所有换算函数toWei/fromWei/toNumber等共用的保护机制。十六进制转换toHex 对纯数字字符串的处理变了toHex在两个版本中的绝大多数行为一致唯一差异是仅包含数字的字符串// 1.x new Web3().utils.toHex(0x1); // 0x1 new Web3().utils.toHex(0x1); // 0x1 new Web3().utils.toHex(1); // 0x1 new Web3().utils.toHex(1); // 0x1数字字符串被当作数字 // 4.x new Web3().utils.toHex(0x1); // 0x1 new Web3().utils.toHex(0x1); // 0x1 new Web3().utils.toHex(1); // 0x1 new Web3().utils.toHex(1); // 0x31按字符串处理即字符 1 的 ASCII 十六进制原因在 packages/web3-utils/src/converters.ts 的toHex分支逻辑中清晰可见4.x 对字符串先检查是否0x/-0x前缀走numberToHex再检查isHexStrict原样返回随后才根据isHex/isInt/isUInt的组合判断纯数字字符串1会被当作普通字符串做 UTF-8 编码因此1的十六进制是0x31。注意toHex对字符串输入遵循除非以0x为前缀否则一律按字符串处理的规则。迁移排查清单凡是对可能为数字的字符串调用toHex的代码要么预先用Number()/BigInt()转换要么确保输入带0x前缀。校验函数迁移从 web3-utils 到 web3-validator4.x 将全部校验函数isAddress、isBloom、isInBloom、isTopic、checkAddressCheckSum、isHex、isHexStrict等迁移到了新包web3-validator。为兼容 1.x 代码web3-utils仍保留这些导出但在源码中明确标注了 deprecated 并提示迁移见 packages/web3-utils/src/validation.ts 中大量deprecated Will be removed in next release. Please use web3-validator package instead.注释且每个函数实质上是web3-validator同名实现的再导出// 1.x / 4.x可用但已弃用会收到弃用告警 import { isAddress, isHex } from web3-utils; // 4.x推荐 import { isAddress, isHex, isHexStrict } from web3-validator;web3-validator的校验实现集中在 packages/web3-validator/src/validation 目录下isHex/isHexStrict的具体正则见 packages/web3-validator/src/validation/string.ts。isHex负数返回 trueisHex(-123); // 1.x 返回 false4.x 返回 true // true新实现的正则^((-0x|0x|-)?[0-9a-f]|(0x))$允许可选的-前缀因此-123被视为合法十六进制表示注意-0x单独不匹配。isHex空字符串返回 falseisHex(); // 1.x 返回 true4.x 返回 false // false空串不满足上述正则中至少一个十六进制字符的要求。isHex / isHexStrict-0x 返回 falseisHex(-0x); // 1.x 返回 true4.x 返回 false // false isHexStrict(-0x); // 1.x 返回 true4.x 返回 false // falseisHexStrict的正则^((-)?0x[0-9a-f]|(0x))$要求0x之后至少跟一个十六进制字符packages/web3-validator/src/validation/string.ts所以-0x、0x均不通过严格校验。stripHexPrefix改从 web3-eth-accounts 导入stripHexPrefix在 4.x 中从web3-utils移至web3-eth-accounts实现位于 packages/web3-eth-accounts/src/common/utils.ts对非字符串输入会抛类型错误// 4.x import { stripHexPrefix } from web3-eth-accounts; console.log(stripHexPrefix(0x123)); // 123从源码看该函数同时被web3-eth-accounts内部大量使用如 nonce 补零、RLP 编码前的十六进制规范化等见 packages/web3-eth-accounts/src/common/utils.ts 与 packages/web3-eth-accounts/src/common/utils.ts这也是它被下沉到账户包的原因。若需在web3-utils中获取同等能力可自行用str.replace(/^0x/i, )替代。compareBlockNumbers只允许同类比较compareBlockNumbers(blockA, blockB)用于比较两个区块位置区块号或区块标签返回-1A B、0相等或1A B。4.x 收紧了入参约束要么两边都传区块标签要么两边都传区块数字唯一例外是earliest与数字0的等价比较。compareBlockNumbers(earliest, safe); // 合法返回 -1 compareBlockNumbers(8692, 2); // 合法返回 1 compareBlockNumbers(latest, 500); // 1.x 返回 14.x 抛 InvalidBlockError源码逻辑packages/web3-utils/src/validation.ts按以下顺序执行相等短路blockA blockB或(earliest|0)与(earliest|0)的组合返回0earliest 特判任一方为earliest时直接返回-1/1这是标签与数字混比的唯一豁免且测试覆盖了[earliest, 2]、[2, earliest]等组合双标签比较按earliest → finalized → safe → latest → pending的递增顺序内部tagsOrder映射为 1~5返回-1/1标签与数字混比直接抛InvalidBlockError(Cannot compare blocktag with provided non-blocktag input.)双数字比较用BigInt精确比较支持 number、string、bigint 混用。测试用例完整验证了上述行为packages/web3-utils/test/fixtures/validation.ts合法数据包括[earliest, 0]、[0, earliest]、[[safe, pending], -1]等非法数据则覆盖[latest, 110]、[[22, finalized], errorObj]、[pending, BigInt(1)]等所有标签与数字混比组合均断言抛出InvalidBlockError。迁移注意1.x 代码中若存在数字区块号与latest/pending标签比较的逻辑例如判断某区块是否已确认需改写为先获取对应标签的区块号再比较或改用BlockTags之间的比较避免运行时抛错。迁移实战检查清单完成上述逐项改造后建议按以下清单回归验证搜索BN仓库内所有Web3.utils.BN/new BN(...)用法替换为BigInt(...)并检查toString()、比较运算等跨类型操作搜索toWei/fromWei确认所有调用都传入了单位参数字符串或十进制指数搜索toHex(纯数字字符串)确认输入带0x前缀或先转数字防止1 → 0x31这类静默语义变化搜索isHex/isHexStrict的边界输入关注负数、空串、-0x三类返回值变化web3-validator 校验实现搜索stripHexPrefix的导入来源统一改为web3-eth-accounts搜索compareBlockNumbers的混比调用标签与数字混比需改写必要时捕获InvalidBlockErrorweb3-errors 错误码定义检查弃用告警对web3-utils中 deprecated 的校验函数统一改导web3-validator。需要说明的是本文所有行为差异均以当前仓库web3.js 4.x 系列源码与测试为据若你的项目锁定在特定 4.x 小版本建议以该版本发布说明为准做最终核对。其他包的迁移可继续参考本升级指南目录下的 accounts_migration_guide、providers_migration_guide 等姊妹篇。【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考