Node.js环境下怎么运行JavaScript脚本文件

在 Node.js 环境下运行 JavaScript 脚本文件，核心操作是在系统命令行或终端中使用 node 命令后跟目标文件的路径。Node.js 提供了脱离浏览器的独立执行环境，借助 Google V8 引擎直接将 JavaScript 代码编译为本地机器码运行，因此只要系统安装了 Node.js 运行时，就可以随时执行本地的 .js 文件。

一、准备工作：确认 Node.js 安装与环境状态

运行任何脚本之前，首先需要确认操作系统中已经正确安装了 Node.js 并配置了全局环境变量。这一步可以排除后续运行时因找不到执行程序而导致的命令报错。

打开系统的终端工具（macOS 或 Linux 用户打开 Terminal，Windows 用户可使用 PowerShell 或 CMD），输入以下命令并回车：

node -v

命令输出示例：

v18.17.0

如果终端返回了形如 v18.x.x 或 v20.x.x 的版本号，说明 Node.js 已处于就绪状态，可以正常执行后续的脚本调用。如果终端提示 command not found: node 或 'node' 不是内部或外部命令，则表示尚未安装 Node.js，或者安装后未将安装路径添加到系统的 PATH 环境变量中。

二、从零编写并运行第一个脚本文件

运行脚本的过程可以分为编写代码文件、定位终端路径以及执行运行命令三个环节。

1. 新建脚本文件

使用任意文本编辑器（例如 VS Code、Sublime Text 或系统自带的记事本），在工作目录中新建一个名为 app.js 的纯文本文件，并在其中输入如下测试代码：

// app.js
const message = "Hello, Node.js!";
console.log(message);
console.log("当前脚本正在由 Node.js 运行时解析并执行。");

保存文件后，记下该文件所在的目录路径。

2. 在终端中执行脚本

要执行刚刚创建的脚本，最稳妥的做法是将终端的工作目录切换至 app.js 所在位置。假设文件存放在 ~/projects/demo 目录下，可以在终端执行：

cd ~/projects/demo
node app.js

命令输出示例：

Hello, Node.js!
当前脚本正在由 Node.js 运行时解析并执行。

执行完成后，Node.js 会在输出打印结果后自动释放内存并退出进程，终端光标恢复等待输入状态。

三、路径定位与命令行参数传递

在实际开发过程中，运行脚本往往不仅限于在同一目录下输入文件名，还涉及灵活的路径调用以及参数传递。

1. 文件路径的不同指定方式

node 运行时能够接受相对路径和绝对路径：

• 当前目录与子目录（相对路径）：如果终端在项目根目录，运行 src 目录下的 server.js，可以输入 node src/server.js 或 node ./src/server.js。
• 绝对路径：无论终端当前处于哪个目录，都可以直接传递完整的文件系统路径。例如在 macOS/Linux 下执行 node /var/www/project/index.js，在 Windows 下执行 node C:\projects\demo\index.js。
• 路径包含空格：当文件路径中含有空格字符时，必须使用双引号将路径包裹起来，如 node "D:\my scripts\task.js"，否则 Node.js 会将空格截断并将后半段误判为参数。

2. 向运行中的脚本传递命令行参数

运行脚本时，可以在文件名后紧跟自定义参数。Node.js 提供了全局对象 process.argv，它是一个包含所有命令行调用参数的字符串数组。

编写示例文件 params.js：

// params.js
console.log("完整参数数组：", process.argv);

// 获取用户自定义的参数（从索引 2 开始）
const customArgs = process.argv.slice(2);
console.log("用户传递的有效参数：", customArgs);

在终端中带参数运行该脚本：

node params.js build --mode=production v1.0

命令输出示例：

完整参数数组： [
  '/usr/local/bin/node',
  '/Users/demo/params.js',
  'build',
  '--mode=production',
  'v1.0'
]
用户传递的有效参数： [ 'build', '--mode=production', 'v1.0' ]

从输出中可以看出，process.argv[0] 始终是 Node.js 运行时可执行文件的物理绝对路径，process.argv[1] 始终是正在被执行的脚本文件绝对路径，而真正的业务参数则从下标 2 开始排布。

四、CommonJS 与 ES Module 两种模块规范的运行差异

现代 JavaScript 生态中存在 CommonJS 和 ES Module（ESM）两套主流模块标准。在 Node.js 中运行包含模块导入导出的脚本时，需要遵循相应的配置规范。

1. CommonJS 规范（Node.js 传统默认模式）

CommonJS 使用 require() 加载模块，使用 module.exports 导出模块。在未作任何额外配置时，Node.js 默认将所有 .js 文件视作 CommonJS 模块处理：

// math.js
function add(a, b) {
  return a + b;
}
module.exports = { add };

// main.js
const { add } = require('./math.js');
console.log("计算结果：", add(10, 20));

运行 node main.js 即可正常输出 计算结果： 30。

2. ES Module 规范（现代 ECMAScript 标准模式）

如果脚本使用了现代规范的 import 和 export 语法，直接用 node script.js 执行会抛出语法错误。在 Node.js 中运行 ES Module，必须满足以下两项条件之一：

1. 使用 .mjs 后缀：将文件命名为 main.mjs，Node.js 会强制按 ESM 模式解析。
2. 配置 package.json：在同级或上级目录的 package.json 中添加 "type": "module" 声明。设置后，该目录范围内的所有 .js 文件都会被当作 ESM 解析。

// 方式 A：package.json
{
  "name": "demo",
  "type": "module"
}

// 方式 B：直接命名为 main.mjs
import { readFileSync } from 'fs';
console.log("ES Module 运行成功！");

五、运行中常见错误与排查方法

新手在运行脚本时，常会遇到以下三种典型报错，了解其产生机理可以快速定位原因：

1. 报错：Error: Cannot find module

Error: Cannot find module '/Users/demo/test.js'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1077:15)
    code: 'MODULE_NOT_FOUND'

排查与解决：该错误表明 Node.js 在指定的路径上未找到该文件。首先检查当前终端的工作目录（Linux/macOS 执行 pwd，Windows 执行 cd），确认当前所在位置与目标文件相对路径是否匹配；其次检查文件名大小写及拼写，很多操作系统（如 Linux）对文件名大小写敏感。

2. 报错：SyntaxError: Cannot use import statement outside a module

SyntaxError: Cannot use import statement outside a module
    at internalCompileFunction (node:internal/vm:73:18)

排查与解决：表明在默认的 CommonJS 模式下直接使用了 ES6 import 语法。解决方法是将文件后缀改为 .mjs，或者在项目根目录下创建 package.json 并写入 {"type": "module"}。

3. 报错：ReferenceError: window is not defined 或 document is not defined

ReferenceError: window is not defined
    at Object.<anonymous> (/Users/demo/app.js:2:1)

排查与解决：浏览器中存在的 DOM 和 BOM 全局对象（如 window、document、localStorage）在 Node.js 服务端环境中是不存在的。Node.js 提供了 global、process、Buffer 等服务端全局对象。涉及浏览器特有 API 的代码不能直接在 Node.js 中执行。

六、高效开发：脚本运行方式与场景决策

在日常项目开发与运维中，除了简单的 node script.js，还可以根据应用场景选用更高效的运行方式：

• 开发阶段的热重载运行（无需手动重启）：在 Node.js 18.11+ 版本中，官方内置了监听机制，可以直接执行 node --watch app.js。当 app.js 或其依赖的文件发生变动并保存时，Node.js 会自动重启脚本。低版本则通常搭配全局安装的 nodemon app.js 达到同样效果。
• 通过 package.json scripts 统一管理：在团队协作项目中，通常将启动命令配置在 package.json 的 scripts 字段中。例如配置 "start": "node server.js"，团队成员只需统一运行 npm start 或 npm run dev，无需手动记忆长路径或环境变量。
• 临时调试与简单计算（REPL 交互环境）：在终端直接输入单独的 node 不带任何文件名回车，即可进入 Node.js 的交互式解释器（REPL）。在其中可以直接输入任意 JavaScript 表达式进行求值验证，按两次 Ctrl + C 即可退出。