如何将Yarn工作区Monorepo升级至Node.js 18？含BigInt报错处理

一、基础升级步骤 #

• 切换到Node.js 18：用nvm或官方安装包完成升级，执行node -v确认版本为18.x.x
• 升级Yarn到3.x：在项目根目录运行yarn set version stable，随后执行yarn install重新拉取依赖
• 同步Yarn配置：检查根目录.yarnrc.yml，确认nodeLinker配置符合需求（推荐node-modules适配多数场景，若用PnP需确保Jest支持）
• 更新TypeScript依赖：升级typescript到4.7+版本（支持Node18），同时安装@types/node@18，执行命令：yarn add -D typescript @types/node@18 --workspaces

二、解决TypeError: BigInt.prototype.toString requires that 'this' be a BigInt报错 #

这个报错核心是BigInt类型处理不兼容，以下是针对性解决方案：

1. 排查并升级第三方依赖 #

• 用yarn why命令定位调用BigInt的依赖，比如yarn why bigint，找到后升级该依赖到最新版本（多数旧库在Node18下已修复BigInt兼容问题）
• 若找不到具体依赖，可全局搜索项目代码中的BigInt调用，排查是否有第三方库的调用逻辑异常

2. 修正TypeScript配置与代码 #

• 检查tsconfig.json：确保target设为ES2020或更高，lib数组包含ES2020（或ES2020.BigInt），保证编译时正确处理BigInt类型
• 排查代码中的类型错误：比如是否存在将普通数字/字符串强制断言为BigInt后调用toString的情况，示例错误代码：

  const num = 123;
  (num as unknown as BigInt).toString(); // 错误：非BigInt类型调用BigInt方法
  

  修复这类错误，确保只有真正的BigInt实例调用toString

3. 升级Jest及适配配置 #

• 升级Jest生态依赖：将jest升级到29.x版本，同步升级ts-jest和@types/jest到对应兼容版本，执行命令：yarn add -D jest@latest ts-jest@latest @types/jest@latest --workspaces
• 检查Jest配置：确保testEnvironment设为node（默认值，但避免误设为jsdom，后者对BigInt支持有限）
• 若使用Yarn PnP模式，需在jest.config.js中添加PnP解析支持：

  module.exports = {
    resolver: require.resolve('jest-pnp-resolver'),
    moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
  };
  

4. 切换Yarn链接模式测试 #

• 若使用PnP模式仍报错，可临时切换到node-modules模式验证：在.yarnrc.yml中设置nodeLinker: node-modules，执行yarn install后重新测试，若报错消失则说明PnP对特定依赖兼容不足

三、验证升级结果 #

• 执行yarn build确认TypeScript编译无错误
• 执行yarn test确保Jest测试全部通过
• 在Node18环境下启动项目，验证核心功能正常运行

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