Node.js 中 -r 或 --require 命令行选项的用途与实践详解-js教程-PHP中文网

Node.js 中 -r 或 --require 命令行选项的用途与实践详解

-r（或 --require）用于在执行主脚本前预加载指定模块，常用于注入全局行为、启用编译器（如 ts-node）、修改内置对象或设置运行时环境，但不适用于直接导出函数供 REPL 使用。

`-r`（或 `--require`）用于在执行主脚本前预加载指定模块，常用于注入全局行为、启用编译器（如 ts-node）、修改内置对象或设置运行时环境，但不适用于直接导出函数供 repl 使用。

-r 是 Node.js 提供的一个强大而灵活的命令行选项，全称 --require，其核心作用是：在 Node.js 启动并加载用户主模块（如 index.js）之前，先执行并加载一个指定的模块。该机制不依赖于 require() 调用，而是由运行时强制注入，因此能影响整个模块加载上下文——包括全局对象、内置模块行为，甚至 ES 模块解析流程（需配合 --experimental-specifier-resolution 等标志）。

✅ 正确使用场景与原理

-r 加载的模块会以 CommonJS 方式执行（即使主项目使用 ES 模块），且其顶层代码立即运行。这意味着你可以在其中：

修改全局变量（如 console.log、process.env）；
注册全局钩子（如 process.on('uncaughtException')）；
启用语言扩展（如 ts-node/register、esbuild-register）；
预设 Polyfill 或 Mock（如 dotenv/config）；

但需注意：-r 不会将模块的 exports 或 export 绑定到全局作用域，也不会让后续代码自动访问其命名导出（如 areaOfCircle）。这就是为什么你的 circle.js 在 -r 下运行后，进入 REPL 时仍报错 areaOfCircle is not defined —— 因为 export areaOfCircle 是 ES 模块语法，而 -r 以 CommonJS 模式加载 .js 文件（Node 默认不解析 ESM 导出），且即使解析成功，导出也不会挂载到全局。

? 实用示例

示例 1：劫持 console.log

// hook.js
const origLog = console.log;
console.log = (...args) => origLog('[HOOKED]', ...args);

// app.js
console.log('Hello from app!');

运行：

node -r ./hook.js app.js

输出：

用于自动切换项目中适合的node 版本

根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。

下载

[HOOKED] Hello from app!

示例 2：自动加载环境变量（无需 require('dotenv').config()）

node -r dotenv/config app.js dotenv_config_path=./.env

示例 3：启用 TypeScript 运行时（需已安装 ts-node）

node -r ts-node/register src/index.ts

示例 4：注入调试工具（如 why-is-node-running）

node -r why-is-node-running index.js

⚠️ 常见误区与注意事项

❌ 不要用 -r 替代主入口：node -r circle.js 启动的是 Node REPL，但 circle.js 的 export 在 CommonJS 上下文中无效，且导出不会自动暴露给 REPL 全局。若想复用函数，请改用 node circle.js 并在文件末尾添加 global.areaOfCircle = areaOfCircle;（CommonJS 风格），或改写为：
```
// circle.cjs （显式使用 .cjs 后缀触发 CommonJS）
function areaOfCircle(radius) {
  return Math.PI * radius ** 2;
}
global.areaOfCircle = areaOfCircle; // 显式挂载到 global
```
✅ ESM 支持限制：Node.js 目前（v20+）对 -r + ES 模块的支持有限。若必须用 ES 导出，可借助 --loader（实验性）或转为 CommonJS；更推荐的做法是将逻辑封装为 CLI 工具或通过 import() 动态加载。
? 安全提示：-r 加载的代码拥有完全执行权限，切勿在不受信环境中加载任意路径（如 ${XDG_RUNTIME_DIR}/xxx.js），存在严重安全隐患。

✅ 最佳实践总结

场景	推荐方式
需全局函数（如 REPL 中调用）	主脚本中 require() 或显式 global.xxx = xxx
需提前配置/拦截行为	✅ -r 是理想选择（如日志增强、env 注入）
需运行 TypeScript/JSX/ESNext	✅ -r ts-node/register 或 -r esbuild-register
需类型安全的模块复用	使用标准 import/require，而非依赖 -r 暴露符号