第一次运行 Node.js：终端里的 JavaScript 怎样执行

本文是「Node 运行现场」系列的第 2 篇。

本篇面向刚开始接触 Node.js 的前端开发者，只说明怎样在终端中执行一个 JavaScript 文件，以及运行失败时应该先检查什么。

前端代码平时由浏览器加载。写进 .js 文件后，通常要通过网页里的 <script> 标签，或者交给 Vite 这类开发工具处理。

安装 Node.js 以后，多了一种更直接的运行方式：在终端输入文件名，让 Node.js 执行这份 JavaScript。

例如项目中有一个 hello.js：

const name = 'Node.js'

console.log(`你好，${name}`)

在文件所在目录执行：

node hello.js

终端会输出：

你好，Node.js

这条命令中，node 是用来运行 JavaScript 文件的命令，hello.js 是本次执行的文件。命令运行后，Node.js 会读取文件内容并依次执行其中的代码，日志会直接输出到终端。

一、运行代码前先确认 node 命令可以使用

安装 Node.js 后，可以先在终端执行：

node --version

如果安装和命令配置正常，终端会输出一个版本号，例如：

vxx.x.x

这里不需要追求某个固定数字。实际项目可能会在 README、团队文档或 package.json 中声明版本要求，进入项目后再按项目要求选择版本。

如果终端提示找不到 node，常见原因有：

• Node.js 还没有安装
• 安装完成后终端没有重新打开
• node 命令所在目录没有加入系统的命令搜索路径
• 当前使用的终端环境没有读取到最新配置

这时 JavaScript 文件本身还没有开始执行。问题出在终端找不到 Node.js，应先处理安装或命令配置。

二、node hello.js 这条命令分别表示什么

下面这条命令只有两部分：

node hello.js

可以拆成：

node
→ 使用 Node.js 运行代码

hello.js
→ 本次交给 Node.js 执行的文件

Node.js 官方入门文档给出的常见运行方式，就是安装 Node.js 后，在终端调用全局可用的 node 命令，并把文件名传给它。

假设当前目录中有下面两个文件：

node-demo/
├─ hello.js
└─ price.js

执行：

node hello.js

只会运行 hello.js。

执行：

node price.js

运行的则是 price.js。

Node.js 不会因为两个文件放在同一个目录，就自动把它们全部执行。文件之间怎样导入和导出，会在后面的模块文章中说明。

三、Node.js 会按代码顺序得到什么结果

先创建一个能够直接运行的 hello.js：

const productName = '机械键盘'
const price = 299
const count = 2

const total = price * count

console.log('商品：', productName)
console.log('数量：', count)
console.log('总价：', total)

在这个文件所在目录执行：

node hello.js

终端输出：

商品： 机械键盘
数量： 2
总价： 598

这段代码里的变量、乘法运算和 console.log() 都是 JavaScript。Node.js 读取文件后执行这些代码，并把日志写到当前终端。

当前示例没有访问文件、没有发送网络请求，也没有使用第三方库。它只证明了一件事：JavaScript 文件可以不依赖网页，直接由 Node.js 在终端环境中执行。

代码执行到最后一行后，没有其他工作需要继续处理，命令结束，终端重新等待下一条输入。定时器、网络服务为什么可能让程序继续运行，会在后面的文章中单独解释。

四、修改文件后为什么需要重新执行命令

把 count 从 2 改成 3：

const productName = '机械键盘'
const price = 299
const count = 3

const total = price * count

console.log('商品：', productName)
console.log('数量：', count)
console.log('总价：', total)

保存文件后，之前执行过的命令不会自动重新运行。需要再次输入：

node hello.js

新的输出是：

商品： 机械键盘
数量： 3
总价： 897

每次执行 node hello.js，Node.js 都会重新读取当前保存的文件内容，再运行一遍。

如果编辑器里的修改还没有保存，终端执行的仍然是磁盘上上一次保存的内容。页面开发中，Vite 等工具经常会监听文件变化并自动刷新。直接使用 node hello.js 时，不应默认存在这套行为。

部分 Node.js 版本提供监听文件变化并重新启动的命令选项，但本篇不依赖这项能力，也不展开版本差异。第一次运行时，手动保存并重新执行最容易观察代码变化。

五、文件明明存在，为什么命令仍然找不到它

假设文件位于：

D:\code\node-demo\hello.js

终端却停留在另一个目录：

D:\code

此时执行：

node hello.js

Node.js 会尝试根据当前命令所在的位置查找 hello.js。当前目录没有这个文件，就会出现找不到入口文件的错误，内容通常包含：

Cannot find module

这里的重点不是模块机制，而是命令中的相对文件位置没有对应上。

可以采用两种处理方式。

第一种，先进入文件所在目录，再运行：

cd node-demo
node hello.js

第二种，传入包含目录的路径：

node node-demo/hello.js

路径分隔符和绝对路径写法会受到操作系统影响，本篇不展开。先记住一个检查方法：执行 node hello.js 之前，确认当前终端所在目录中确实能看到 hello.js。

六、代码写错后，错误会出现在哪里

把示例故意写错，漏掉字符串右侧的引号：

const name = 'Node.js

console.log(name)

执行：

node hello.js

Node.js 无法正常解析这段 JavaScript，终端会显示 SyntaxError，并指出出错文件和附近位置。

此时可以先检查：

1. 错误中显示的是不是自己刚才运行的文件；
2. 文件是否已经保存；
3. 报错行附近是否缺少引号、括号或逗号；
4. 修改后是否重新执行了命令。

再看一个运行阶段的错误：

const price = 299

console.log(total)

这段代码语法可以被读取，但运行到 console.log(total) 时，total 没有定义，终端会显示类似：

ReferenceError: total is not defined

两类错误发生的位置不同：

错误类型	发生情况	优先检查
找不到命令	终端无法启动 Node.js	安装和命令配置
找不到文件	Node.js 没找到入口文件	当前目录与文件路径
SyntaxError	JavaScript 代码无法正常解析	引号、括号、语法位置
ReferenceError	代码运行时使用了不存在的变量	变量声明和名称

看到报错时，先判断代码有没有开始执行，比直接修改一大段代码更容易缩小范围。

七、终端输出和网页内容有什么区别

在 Node.js 文件中执行：

console.log('任务完成')

内容会出现在启动命令的终端中。

在浏览器页面中执行同样的代码，内容通常出现在浏览器开发者工具的 Console 面板中。

console.log() 的写法相同，但输出位置取决于代码运行在哪里：

运行位置	怎样启动	日志通常出现在哪里
浏览器	网页加载脚本	浏览器开发者工具
Node.js	node hello.js	当前终端

Node.js 默认没有网页可以更新，因此下面的代码不能作为终端示例直接运行：

document.querySelector('#app')

它依赖浏览器提供的页面对象。Node.js 能运行 JavaScript，不代表浏览器里的每个 API 都会跟着出现。

后续使用 Node.js 读取文件或启动 HTTP 服务时，会逐步接触它提供的运行能力。本篇只处理 JavaScript 文件怎样被启动和观察。

八、第一次运行失败时可以怎样排查

一份最小文件没有成功运行时，可以按照命令执行顺序检查：

终端能否找到 node
→ node 能否找到 JavaScript 文件
→ JavaScript 能否正常解析
→ 代码运行时是否使用了错误变量
→ 输出是否出现在当前终端

对应到操作上：

node --version
node hello.js

然后查看：

• hello.js 是否存在；
• 终端是否位于正确目录；
• 编辑器是否已经保存；
• 报错文件名和行号是否与当前文件一致；
• 代码是否使用浏览器专用对象。

这套检查只适用于当前的单文件示例。项目加入 npm、模块、环境变量和第三方依赖后，命令入口和错误来源会增加，后续文章会逐步补上。

九、小结

第一次运行 Node.js，不需要先理解复杂的运行机制。创建一个 JavaScript 文件，在文件所在目录执行 node 文件名.js，就可以观察代码输出。终端接收命令，node 启动 Node.js，文件名决定这次运行哪份代码。

运行失败时，可以顺着命令检查：终端是否认识 node、入口文件是否位于正确位置、文件是否保存、JavaScript 是否存在语法或变量错误。问题发生在哪一步，决定应该检查安装、路径还是代码。

当前示例只运行了一个独立文件，还没有涉及 npm、package.json、文件之间的导入、命令行参数和自动重启。下一篇会把 Node.js、npm 与 package.json 放到同一个前端项目中，说明三者分别负责什么。

参考资料

• Node.js 官方入门：Introduction to Node.js
• Node.js 官方入门：Run Node.js scripts from the command line
• Node.js 官方文档：Command-line API