Node.js 12环境下FinalizationRegistry未定义问题的解决咨询

给你几个实用的解决思路，按优先级从高到低推荐：

1. 直接替换/移除exit-free-leak包 #

这是最省心的方案，毕竟依赖包本身依赖高版本Node API，能不用就不用：

• 先确认这个包是直接依赖还是间接依赖：运行npm ls exit-free-leak查看依赖链。
• 如果是你手动引入的，先检查项目代码里有没有用到它的核心功能——如果不是必须的，直接删掉相关代码，再执行npm uninstall exit-free-leak移除包。
• 如果是间接依赖（比如由其他包引入），可以尝试升级/降级父依赖包，找一个不依赖exit-free-leak的版本；或者用npm override（npm 8+支持）强制替换exit-free-leak为兼容Node12的替代包（如果存在的话）。

2. 给Node12 Polyfill缺失的API #

如果必须保留exit-free-leak，可以通过polyfill补上Node12没有的FinalizationRegistry和WeakRef：

• 安装兼容的polyfill包，比如@ungap/weakref：

  npm install @ungap/weakref --save
  

• 在Express项目入口文件的最顶部引入polyfill（必须确保在其他代码之前加载）：

  // 入口文件如app.ts或index.ts
  import '@ungap/weakref';
  // 若为CommonJS格式则用：
  // require('@ungap/weakref');
  

• 也可以用core-js提供的细分polyfill：

  npm install core-js --save
  

  import 'core-js/es/weak-ref';
  import 'core-js/es/finalization-registry';
  

3. 调整TypeScript编译配置适配Node12 #

你的项目原本基于Node16开发，需要把TS配置改成符合Node12的标准：

• 修改tsconfig.json的关键配置：

  {
    "compilerOptions": {
      "target": "ES2019", // Node12原生支持到ES2019
      "lib": ["ES2019"], // 不要包含ES2021+的库
      "module": "CommonJS", // Node12默认支持CommonJS
      "types": ["node"],
      "typeRoots": ["node_modules/@types/node@12"], // 对应Node12的类型定义
      "skipLibCheck": true
    }
  }
  

• 安装对应版本的类型定义：

  npm install @types/node@12 --save-dev
  

• 重新编译项目：tsc，确保编译后的代码没有依赖高版本JS特性。

额外注意事项 #

• 安装依赖时，切换到Node12环境（比如用nvm）再执行npm install，这样npm会自动选择适配Node12的包版本，避免引入不兼容依赖。
• 部署到DreamHost Passenger时，确保package.json里指定正确的Node版本：

  {
    "engines": {
      "node": "12.x"
    }
  }
  

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