Node.js中BIP39种子调用hdkey.fromMasterSeed报Uint8Array错误求助

问题场景 #

在基于Node.js 20的NX单仓库TypeScript项目中，实现BIP39/BIP32密钥派生时遇到一致错误：使用bip39库的mnemonicToSeedSync返回的Buffer作为主种子，调用hdkey库或ethereumjs-wallet内置的hdkey.fromMasterSeed方法时，均抛出如下错误：

Expected private key to be an Uint8Array

错误栈详情：

28 |
29 | const seed = mnemonicToSeedSync(mnemonic);
30 | const hdWallet = hdkey.fromMasterSeed(seed);
| ^
31 | const wallet = hdWallet
32 | .derivePath(EthereumECIES.primaryKeyDerivationPath)
33 | .getWallet();

at assert (../../node_modules/secp256k1/lib/index.js:18:20)
at isUint8Array (../../node_modules/secp256k1/lib/index.js:22:3)
at Object.privateKeyVerify (../../node_modules/secp256k1/lib/index.js:66:7)
at Object.privateKeyVerify (../../node_modules/ethereum-cryptography/src/shims/hdkey-secp256k1v3.ts:4:20)
at HDKey.set (../../node_modules/ethereum-cryptography/vendor/hdkey-without-crypto.js:46:26)
at Function.Object..HDKey.fromMasterSeed (../../node_modules/ethereum-cryptography/vendor/hdkey-without-crypto.js:194:20)
at Function.fromMasterSeed (../../node_modules/ethereumjs-wallet/src/hdkey.ts:13:36)
at Function.generateKeyPairFromMnemonic (src/lib/cryptoWallet.ts:30:28)
at Object. (src/lib/cryptoWallet.spec.ts:8:29)

已调试确认mnemonicToSeedSync返回的确实是Buffer类型，但两个工具库均触发相同错误，推测为子依赖兼容性问题。

错误成因 #

1. 类型校验逻辑缺陷：报错链中的secp256k1旧版本的isUint8Array函数仅通过instanceof Uint8Array判断类型，未适配Node.js中Buffer作为Uint8Array子类的特性。在TS编译后的跨模块环境（如CommonJS与ES模块混合）中，Buffer的instanceof Uint8Array判断可能因模块上下文差异返回false，导致校验失败。
2. 依赖版本冲突：NX单仓库的依赖扁平化处理可能导致不同子包引入了不同版本的secp256k1或ethereum-cryptography，部分旧版本依赖未适配Node.js 20的Buffer类型判断逻辑。
3. 工具库参数处理遗漏：hdkey的fromMasterSeed方法内部会将种子派生为私钥后传入secp256k1校验，若中间步骤未自动完成Buffer到Uint8Array的兼容转换，就会触发错误。

解决方法 #

• 显式转换类型：将mnemonicToSeedSync返回的Buffer直接转换为Uint8Array后传入：

  const seed = mnemonicToSeedSync(mnemonic);
  const seedUint8 = new Uint8Array(seed);
  const hdWallet = hdkey.fromMasterSeed(seedUint8);
  

• 升级依赖版本：将secp256k1、ethereumjs-wallet、hdkey、bip39升级至支持Node.js 20的最新稳定版，新版本通常已修复Buffer与Uint8Array的兼容判断问题。
• 锁定依赖版本：在NX根目录的package.json中使用overrides字段（npm）或resolutions字段（Yarn）统一锁定secp256k1和ethereum-cryptography的版本，避免子依赖版本不一致：

  // npm示例
  "overrides": {
    "secp256k1": "^5.0.0",
    "ethereum-cryptography": "^2.1.2"
  }
  

内容的提问来源于stack exchange，提问作者Jessica Mulein