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

一、准备工作：确认本地已安装 Node.js

Node.js 是一个脱离浏览器运行的 JavaScript 服务端运行时环境。要运行本地 .js 文件，首先需要确保计算机中已正确配置 Node.js 及其全局环境变量。

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

node -v

如果安装无误，控制台会输出当前安装的 Node.js 版本号，例如：

v20.12.0

若提示 node: command not found 或“不是内部或外部命令”，说明尚未安装 Node.js，或者安装后未将安装路径加入系统的系统变量 PATH 中。此时需要从 Node.js 官网下载对应操作系统的安装包并完成配置后再继续。

二、运行本地脚本的标准操作步骤

执行本地脚本需要四个明确阶段：创建代码文件、定位文件所在目录、在终端触发执行、在控制台获取输出结果。

1. 创建本地 JavaScript 文件

使用任意代码编辑器（例如 VS Code、Sublime Text，甚至系统自带的纯文本记事本），在工作文件夹中新建一个文件，命名为 app.js。在文件中写入简单的输出逻辑：

// app.js
const message = "Hello, Node.js!";
console.log(message);
console.log("当前运行时间:", new Date().toLocaleTimeString());

保存文件并确认扩展名为 .js，避免误存为 .js.txt。

2. 打开终端并定位到脚本所在目录

Node.js 运行时需要知道脚本的存放位置。最直接的做法是将终端的当前工作目录（Current Working Directory）切换到该脚本所在的文件夹。使用 cd 命令切换：

cd /path/to/your-project

例如在 Windows 上进入 D:\projects\demo：

cd /d D:\projects\demo

3. 执行运行命令

在脚本所在目录下，直接输入 node 加上脚本名称：

node app.js

在大多数现代终端中，也可以省略 .js 后缀，Node.js 会自动按模块解析规则补全：

node app

4. 观察控制台输出

终端紧接着会打印代码中的输出信息：

Hello, Node.js!
当前运行时间: 14:20:00

脚本执行完毕后，进程会自动退出，终端恢复可输入提示符状态。

三、理解原理：Node.js 运行环境与浏览器差异

初次在 Node.js 中执行 JavaScript 时，常会疑惑：为什么以往在网页中随手可用的全局对象（例如 window 或 document）在本地脚本中会直接报错？

JavaScript 本质是一门脚本语言规范（ECMAScript），需要由具体的引擎和宿主环境提供 API 支撑：

• 核心引擎一致：两者都通常采用 Google 开源的 V8 引擎解析语法和执行机器码。
• 系统能力差异：浏览器受到沙箱安全限制，不能直接读写用户的本地文件系统；而 Node.js 作为系统级运行时，内置了 fs（文件系统）、path（路径操作）、os（系统信息）、child_process（子进程）等原生模块。
• 顶层对象不同：浏览器的全局顶层对象是 window；Node.js 的顶层对象则是 global，并且没有 DOM 树或 BOM 相关的对象。

四、进阶用法：路径定位与命令行参数传递

在实际开发中，不可能每次都把终端切换到文件同级目录，脚本也经常需要根据外部传入的不同参数执行不同逻辑。

1. 使用相对路径与绝对路径

终端处于任何目录时，都可以通过相对路径或绝对路径直接指向目标脚本文件：

# 相对当前目录运行子目录中的脚本
node ./src/modules/task.js

# 运行上一级目录中的脚本
node ../utils/clean.js

# 使用完整绝对路径运行
node /Users/name/projects/my-app/index.js

2. 传递并接收命令行参数（process.argv）

在命令行中输入脚本名称后，后面跟着的空格分隔的内容都会被作为启动参数传递给 Node.js。可以在脚本内部通过内置的 process.argv 数组获取。

编写一个带参数接收的脚本 greet.js：

// greet.js
// process.argv 是一个包含所有启动命令行参数的数组
const args = process.argv;

console.log("完整 argv 数组:", args);

// 提取用户自定义参数（从下标 2 开始）
const targetName = args[2] || "访客";
const action = args[3] || "欢迎使用";

console.log(`${action}, ${targetName}!`);

在终端中执行并附带两个参数：

node greet.js 开发者 祝工作顺利

控制台输出结果：

完整 argv 数组: [
  '/usr/local/bin/node',
  '/Users/project/greet.js',
  '开发者',
  '祝工作顺利'
]
祝工作顺利, 开发者!

可以看到，process.argv[0] 永远是 Node.js 可执行文件的绝对路径；process.argv[1] 永远是被执行脚本的绝对路径；从 process.argv[2] 开始才是用户在终端中手动追加的实际业务参数。

五、常见报错原因与排查步骤

在实际执行本地 JavaScript 脚本的过程中，通常会遇到以下四种高频报错。掌握这些报错的原因和处理方式，可以快速排查故障。

1. Cannot find module '...'

报错表现：Error: Cannot find module '/path/to/xxx.js'
根本原因：Node.js 在指定路径下找不到对应的脚本文件。
解决方法：

• 使用 ls（macOS/Linux）或 dir（Windows）命令确认当前终端所在目录下是否存在该文件。
• 检查文件名拼写大小写（macOS/Windows 对大小写不敏感，但在 Linux 下严格区分）。
• 检查是否因相对路径层级错误导致定位偏差。

2. ReferenceError: window is not defined 或 document is not defined

报错表现：代码运行到某一行时突然中断，抛出引用错误。
根本原因：代码中调用了浏览器特有的 DOM 或 BOM API（例如 document.getElementById、window.location、alert()）。
解决方法：

• Node.js 服务端环境没有网页渲染引擎，需移除所有针对页面 DOM 的操作代码。
• 若需要调试算法逻辑，将依赖页面交互的部分改为纯函数并使用 console.log 查看返回值。

3. SyntaxError: Cannot use import statement outside a module

报错表现：在代码中使用 import fs from 'fs' 或 export default ... 时报语法错误。
根本原因：Node.js 默认将 .js 文件视为传统的 CommonJS 模块（使用 require() 和 module.exports）。
解决方法（二选一）：

• 方案 A（推荐）：在当前脚本同级或父级目录的 package.json 文件中增加 "type": "module" 配置项。
• 方案 B：将脚本文件的扩展名从 .js 改为 .mjs，Node.js 会强制将其作为 ES Module 运行。

4. 权限受限错误（EACCES: permission denied）

报错表现：在 Linux 或 macOS 系统中直接运行没有执行权限的独立脚本（使用 ./app.js 方式）。
解决方法：通过显式声明 node app.js 调用已安装的 node 运行时，或者通过 chmod +x app.js 赋予脚本可执行权限，并在文件首行添加 Shebang 声明 #!/usr/bin/env node。

六、运行方式速查与操作总结

为了便于快速回顾，以下整理了日常开发中最常用的 Node.js 脚本运行命令及对应的典型应用场景：

掌握上述操作后，即可在任意操作系统中灵活创建并运行本地 JavaScript 脚本，完成数据处理、自动化脚本或后端服务开发。