如何在Node.js运行时不支持ECMAScript模块时输出友好错误？

针对依赖ES模块、顶层await、空值合并运算符（要求Node.js ≥14），但旧版本Node会直接抛出语法错误无法执行提示逻辑的场景，这里提供一个可靠的解决方案：

核心思路 #

用完全不含ES模块语法的CommonJS文件作为唯一入口，先完成版本校验，再通过子进程加载ES模块主程序，确保旧版本Node能正常执行版本判断并输出友好提示。

具体实现 #

1. 编写纯CommonJS入口文件（如cli.js） #

这个文件仅使用旧版本Node支持的CommonJS语法，绝不出现import/export等ES关键字：

// cli.js (纯CommonJS)
const { execFileSync } = require('child_process');

// 手动解析Node版本（无需依赖第三方库）
const currentMajor = parseInt(process.version.slice(1).split('.')[0], 10);
const requiredMajor = 14;

if (currentMajor < requiredMajor) {
  console.error(`错误：本应用需要Node.js ${requiredMajor}或更高版本，当前版本为 ${process.version}。请升级Node.js后重试。`);
  process.exit(1);
}

// 版本符合要求，通过子进程执行ES模块主文件
try {
  execFileSync(process.execPath, ['./src/main.js'], {
    stdio: 'inherit' // 关联子进程与当前进程的输入输出，保证用户体验一致
  });
} catch (err) {
  console.error('应用执行出错：', err.message);
  process.exit(err.exitCode || 1);
}

如果需要更精确的版本校验（比如要求≥14.17.0），可以引入semver库：

// 需先安装semver：npm install semver
const semver = require('semver');

if (!semver.satisfies(process.version, '>=14.17.0')) {
  console.error(`错误：本应用需要Node.js ≥14.17.0，当前版本为 ${process.version}。请升级Node.js后重试。`);
  process.exit(1);
}

2. 配置package.json #

确保package.json的bin和main指向这个CommonJS入口，同时声明你的主代码是ES模块：

{
  "name": "your-cli-app",
  "version": "1.0.0",
  "type": "module",
  "bin": "./cli.js",
  "main": "./cli.js",
  "dependencies": {
    "semver": "^7.5.4" // 若使用semver则添加
  }
}

方案优势 #

• 纯CommonJS入口文件能被所有旧版本Node正常解析，不会触发语法错误，版本判断逻辑稳定执行。
• 通过子进程加载ES模块，避开了CommonJS直接加载ES模块的限制（ERR_REQUIRE_ESM错误）。
• stdio: 'inherit'保证子进程的输入输出与当前CLI进程完全同步，用户体验和直接执行ES模块无差异。

为什么之前的尝试失败？ #

1. CommonJS入口里写静态import：旧版本Node不识别import关键字，直接触发语法错误，根本到不了版本判断逻辑。
2. 用require加载ES模块：Node.js 12+禁止CommonJS用require加载ES模块，会抛出ERR_REQUIRE_ESM。
3. 动态import()：import关键字本身在Node8里就是非法语法，依然会触发语法错误。

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