一直在被身边准备入门编程的朋友问同一个问题我想学后端第一门语言和技术栈选什么最合适我每次的回答都很一致先试试Node.js。理由很简单它上手门槛低、生态足够大、社区资料多而且从安装环境到写出一个能跑起来的程序整个过程最快可能不到半小时。这篇文章就是想带你把编写并运行一个Node.js程序从头到尾走一遍包括环境安装、第一个程序的写法、运行机制、调试方法以及新手最容易踩的坑。不管你是完全没写过代码的小白还是已经会一点HTML/CSS想往后端走的前端同学这篇内容都适合你。我会尽量用大白话解释原理同时把每一步操作讲清楚保证你照着做就能跑通。1. 动手之前先把Node.js的运行逻辑搞清楚很多人第一次听到Node.js会误以为它是一种框架类似Vue、React那种。其实不是。Node.js是一个JavaScript运行时环境它的作用是在浏览器之外执行JavaScript代码。换句话说以前JavaScript只能乖乖待在浏览器里有了Node.js之后它就能在服务器上跑读写文件、访问网络、处理请求这些能力它全都有了。1.1 Node.js到底是什么把JavaScript从浏览器里解放出来理解Node.js最核心的一点就是运行时环境这五个字。JavaScript本身只是一门编程语言语言规定了怎么写代码但真正让代码执行起来需要有一个环境。浏览器就是最典型的运行环境它提供了一套API比如document.getElementById、window.alert这些能力是浏览器给的。Node.js则基于Chrome浏览器用的V8引擎把JavaScript的执行能力搬到了操作系统层面。它提供了一个完全不同的API集合比如fs模块用来操作文件、http模块用来创建服务器、path模块用来处理文件路径。你可以把它理解成同一个单词换了一套词典——语法还是JavaScript的语法但能力范围完全不同。1.2 浏览器里的JavaScript和Node.js里的JavaScript差在哪为了更直观地感受区别我列一个简单的对照维度浏览器JavaScriptNode.js全局对象window、documentglobal、process如何运行嵌入HTML靠浏览器解析执行node命令直接运行JS文件模块加载ES Moduleimport/export为主CommonJSrequire/module.exports为主也支持ESM能力范围操作DOM、发请求、动画读写文件、创建服务、连接数据库、管理系统资源典型用途页面交互、前端逻辑后端服务、命令行工具、自动化脚本表格最后一行特别关键。现在很多自动化脚本、构建工具、脚手架工具底层全都是Node.js写的包括你可能已经用过的Webpack、Vite、ESLint它们本质都是Node.js程序。1.3 谁适合走这条路学习成本与实际回报如果你已经在写前端代码那学Node.js几乎没有额外语法负担因为语言本身你已经会了。如果你是完全零基础也没关系JavaScript的语法结构在主流语言里算亲和的变量、函数、对象、数组这些概念不难理解而且写出来的代码能立刻在终端里看到结果这种即时反馈对新手来说特别重要。从回报角度看Node.js在中小型项目里出活非常快。做一个简单的文件批量重命名工具、爬虫脚本、接口Mock服务几十行代码就能搞定。很多公司内部的运维工具、数据同步脚本也都是用Node.js写的。学它不会白学哪怕以后不做专职后端它也能在你日常开发中当个瑞士军刀来用。2. 安装Node.js不同系统的完整流程与版本陷阱安装这一步看起来简单其实里面有几个决定你后续开发是否会顺利的关键细节。很多人装完发现node命令找不到、npm装包特别慢、版本不对导致项目跑不起来这些问题大部分都能在安装阶段避免。2.1 版本怎么选LTS和Current的区别Node.js官网提供两种版本下载LTSLong Term Support长期支持版和Current最新尝鲜版。新手我强烈推荐直接选LTS。理由很简单LTS版本会提供长期的安全修复和稳定性保障大多数第三方依赖库也都优先保证对LTS版本的支持。Current版本虽然包含新特性但可能有一些不兼容改动你在学习阶段没必要冒这个险。另外要注意Node.js版本更新很快不同大版本之间在语法特性和模块行为上会有差异。我并不建议追求最新装一个偶数版本且标记为LTS的就好比如常见的18.x、20.x。装完用node -v可以看到当前版本号如果看到类似v20.10.0这样的输出说明安装成功。2.2 Windows安装官网下载包与PATH环境变量的坑Windows平台最简单的安装方式是去Node.js官网下载Windows Installer.msi文件然后一直点下一步。但有一个地方要特别注意安装向导里有一个Add to PATH的选项默认是勾选的千万不要取消。还有自定义安装路径时尽量避开带空格和中文的目录比如C:\Program Files\nodejs\虽然自带空格也能正常工作但有些第三方工具处理这种路径偶尔会抽风自己单独建一个D:\nodejs之类的纯英文路径会更省心。装完之后验证安装打开命令提示符CMD或者PowerShell输入node -v npm -v两个命令都能正常输出版本号就说明安装成功。2.3 macOS和Linux用版本管理器装是最省心的方案macOS用户如果直接去官网下载pkg安装包也能用但我更推荐先装一个Homebrew然后通过它安装或者直接用nvm来管理版本。Linux用户则强烈建议用nvm因为系统包管理器apt、yum里带的Node.js版本通常比较老会在后面装某些新依赖时报错。以macOS配合nvm为例安装命令是两条curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash然后重新打开终端执行nvm install --lts nvm use --lts这样装的好处是你可以随时切换Node.js版本。比如某个老项目需要Node.js 14另一个新项目需要Node.js 20用nvm use 14和nvm use 20就能来回切不用反复卸载重装。我工作这些年因为这个功能少踩了不知道多少坑。2.4 安装完必做的两件事换官方源以外的镜像要考虑清楚很多人装完Node.js之后第一件事就是去网上找命令把npm源切换到国内镜像因为默认源在海外的确慢。这里我给一个中肯的建议如果只是学习阶段装包频率不高用默认源也能忍受如果你已经频繁装包、感觉到明显卡顿再去换镜像也不迟。切换命令一般网上一搜就有我这里不贴具体的了注意一个原则个人开发换源没问题公司项目要按团队规定来别擅自改共享机器的源。另外建议安装完成之后顺手执行一下npm config get registry看到输出是默认官方地址就继续保持如果发现是未知的第三方地址要考虑是不是之前做过什么修改。保持源的可控性后面排查依赖问题会省很多力气。3. 第一个Node.js程序从Hello World到真正用起来环境装好了接下来写代码。这是最关键的一步我会带着你从新建文件夹开始一步步走到一个稍微有点实际功能的程序。3.1 创建项目目录和初始化package.json先在本地新建一个练习项目文件夹。命名上有一个小建议尽量不要用node-demo、project这种让以后回头看的你一脸茫然的名字虽然练习无所谓但养成好习惯从第一天开始总没坏处。我一般会命名为node-learn之类的简短英文路径同样避免中文和空格。接着在终端里进入这个目录执行npm init -y这会自动生成一个package.json文件它是项目的身份证记录着项目名称、版本号、依赖包列表、启动命令等信息。手动创建的话你也可以在文件夹里新建一个文件命名为package.json但我建议用命令生成因为格式不会出错。-y的意思是跳过所有交互提问直接生成默认配置等以后需要自定义了再手动改也不迟。3.2 编写入口文件代码逐行拆解在项目目录下新建一个文件命名为app.js。用任意编辑器打开新手推荐VS Code免费且插件丰富输入下面这段代码// 第一行Node.js代码 const greeting Hello, Node.js!; console.log(greeting);大概解释一下发生了什么const greeting Hello, Node.js!;声明一个字符串变量值是Hello, Node.js!。const表示这个变量不能重新赋值可以理解成只读常量。console.log(greeting);把变量的值打印到终端。console.log是最常用的输出语句不仅仅是Node.js有浏览器里也有作用一样。这个文件虽然短但它完成了一个完整程序的闭环声明数据、处理数据、输出结果。所有编程的基础都在这三件事里打转了。在终端里运行node app.js如果终端输出Hello, Node.js!恭喜你第一个Node.js程序已经成功跑起来了。这一步虽然看起来简单但从0到1的那个1你已经拿到了后面的路会顺畅很多。3.3 理解模块系统require和import到底怎么选上面的例子太简单实际开发里代码会拆分成多个文件一个文件里的代码想被另一个文件复用就需要模块系统。Node.js原生支持两套模块系统CommonJS和ES Module。CommonJS的语法是require和module.exports。我改造一下刚才的例子新建一个utils.js// utils.js const author nodejs新人; function getGreeting(name) { return Hello, ${name}!; } module.exports { author, getGreeting };然后在app.js里这样使用// app.js const { author, getGreeting } require(./utils.js); console.log(getGreeting(author));运行node app.js输出同样正常。这里的核心是module.exports声明了这个文件对外提供什么require(./utils.js)声明了我要引入哪个文件。文件之间彼此隔离只有通过module.exports暴露的内容才能被引用这种设计能有效避免全局变量污染。ES Module的语法则是import和export更现代浏览器原生支持Node.js从12.17版本开始也支持了。要注意的是要在package.json里加一个type: module配置否则Node.js默认按CommonJS处理文件。我建议新手学习阶段先用CommonJS因为它不需要额外配置、报错更直观等熟悉之后再接触ESM理解会更透彻。3.4 接收命令行参数让程序开始有点实际用途纯打印一句话的代码很快就腻了下一步我们做一个稍微有交互感的程序——从命令行接收参数根据不同输入输出不同内容。修改app.js为// app.js const args process.argv.slice(2); if (args.length 0) { console.log(请输入名字例如node app.js 张三); } else { console.log(你好${args[0]}欢迎来到Node.js世界。); }然后运行node app.js 张三输出你好张三欢迎来到Node.js世界。这里process.argv是Node.js提供的一个数组存储着命令行参数。数组前两个元素一个是Node.js执行文件的路径一个是你运行的程序文件的路径所以从索引2开始才是我们真正传入的参数。slice(2)就是从索引2开始截取后面的内容。到这里你的小工具已经能做根据输入产生不同响应的事情了。这就是命令行工具的基本雏形很多Node.js CLI工具就是这么一点点做出来的。4. 运行、调试与开发体验从一次执行到天天开发程序能跑不算完现实开发中你会反复改代码、重启程序、观察输出、定位报错。这一节讲的是让你日常开发更顺畅的运行和调试手段。4.1 node命令的三种常见用法第一直接运行一个JS文件这是最基础的用法node app.js第二直接执行一段代码字符串省去建文件。适合快速验证某个语法node -e console.log(1 1)第三进入REPL交互环境。在终端输入node不带任何参数回车后会进入一个提示符的交互界面可以直接一行一行输入JavaScript代码并立即看到结果类似于浏览器的控制台。想退出就输入.exit或者按两次CtrlC。这个交互环境在调试小语法片段时非常有用。4.2 让程序自动重启node --watch与nodemon学习阶段改完代码还要手动重新node app.js虽然能接受但改多了就烦。Node.js从18.11版本开始内置了一个--watch模式用法就是在运行命令后面加这个参数node --watch app.js这样你每次保存文件程序都会自动重启省去了手动操作。如果你的Node.js版本太老没有这个参数可以安装一个叫nodemon的第三方工具命令是npm install -g nodemon然后运行nodemon app.js它俩实现的热重载效果基本一样--watch的优势是不依赖额外安装nodemon的优势是支持更多自定义配置。以我的经验早期阶段直接用Node.js内置的--watch就完全够了少装一个全局工具多一份省心。4.3 控制台输出的进阶用法别只会console.log新手很容易把console.log当成唯一的调试工具用多了就会发现输出混在一起分不清。Node.js给console对象提供了好几个方法各有用途方法用途示例输出console.log普通打印普通文字console.info信息提示同log但语义不同console.warn警告黄色高亮console.error错误红色高亮console.table表格化数组/对象结构化表格console.time / timeEnd计时执行时间举个例子console.time和console.timeEnd用来测一段代码执行时间很好用console.time(循环耗时); let sum 0; for (let i 0; i 1000000; i) { sum i; } console.timeEnd(循环耗时);运行后会输出类似循环耗时: 5.234ms的结果。以后再遇到这段代码怎么这么慢的疑惑这个方法可以直接帮你定位性能瓶颈在哪里。4.4 报错怎么看读懂堆栈和调试器程序报错不可怕可怕的是看不懂报错。Node.js的报错信息会告诉你三件事错误类型、错误信息和出错位置。比如我故意把代码改成const data undefined; console.log(data.name);运行后终端会输出类似TypeError: Cannot read properties of undefined (reading name) at Object.anonymous (C:\xxx\app.js:2:17)第一行说明错误类型是TypeError具体原因是尝试读取undefined的name属性。第二行开始的堆栈信息指出了出错文件路径和行列位置app.js:2:17意思是app.js文件第2行第17列。看到这个信息直接跳过去看就行。如果console.log打再多也找不出问题可以用Node.js内置调试器。在代码里加上一行debugger;然后运行node inspect app.js程序会在debugger那一行暂停你可以在终端交互式地查看变量。不过说实话现在多数人更习惯在VS Code里点一下行号设断点再按F5启动调试可视化的断点调试对新手友好得多。这里我就不展开VS Code调试配置了后面单独写一篇讲调试环境的搭建。5. 新手最常见的几个坑我踩过之后帮你总结这部分是全文的精华。我见过太多新手在这些地方卡上几个小时甚至一整天我自己当年也一样。提前告诉你这些坑能省下大量无意义的时间。5.1 运行时提示node不是内部或外部命令这是Windows用户高频遇到的问题基本可以断定是安装时没有把Node.js添加到PATH环境变量或者安装后没有重启终端。解决方法是重启终端如果还不行就检查环境变量里是否有一个指向nodejs安装目录的条目。没有的话就手动添加装过一次之后路径一般是C:\Program Files\nodejs。这一关过了后续命令就都通了。5.2 模块找不到Cannot find module背后的三大原因Cannot find module xxx这个报错出现频率极高原因不外乎三种第一拼写错误。这看起来像废话但require的文件名、路径、大小写都必须完全正确比如app.js和App.js在Linux/macOS上是两个不同的文件小写的写错成大写就会报错。第二依赖没有安装。如果你require的是一个npm包比如express但没执行过npm install express那肯定找不到。判断方法很简单看项目里有没有node_modules文件夹没有就说明依赖还没装。第三路径错误。相对路径的理解要清楚./代表当前目录../代表上一级目录。新手经常写错比如require(./utils)在根目录运行没问题但如果在src目录下运行就要改成require(../utils)。5.3 端口被占用EADDRINUSE到底是什么意思当你开始写Web服务器比如用http模块起一个8080端口的服务运行时报Error: listen EADDRINUSE: address already in use :::8080意思是8080端口已经被另一个程序占用了。解决方法是换一个端口或者找到占用端口的进程把它结束掉。Windows上查看端口占用和结束进程的命令是netstat -ano | findstr 8080 taskkill /PID 你的进程号 /FmacOS/Linux上可以用lsof -i :8080 kill -9 你的进程号这类问题在写服务之后会频繁遇到知道在哪查、怎么解决能让你的心态稳很多。5.4 异步代码不按顺序执行理解事件循环的基本逻辑Node.js的一个显著特点是异步非阻塞。看这段代码很多人第一次跑会很困惑console.log(开始); setTimeout(() { console.log(定时器内); }, 0); console.log(结束);输出顺序是开始 结束 定时器内哪怕定时器时间是0毫秒它也会在结束之后才执行。这里不展开讲事件循环的深层机制你只需要先记住一条经验在Node.js里回调函数、Promise这些异步操作不会立刻执行它们会在当前同步代码跑完之后再排队执行。需要按顺序处理多步异步操作时推荐用async/await语法它能让异步代码写起来像同步一样自然function wait(ms) { return new Promise((resolve) setTimeout(resolve, ms)); } async function main() { console.log(开始); await wait(1000); console.log(一秒钟后执行); } main();这段代码输出的顺序是开始、等待一秒、然后一秒钟后执行逻辑清晰多了。async/await是日常开发的基础语法值得在写接口、操作数据库时反复使用。5.5 一个影响深远的习惯用package.json里的scripts管理命令最后一个建议不是踩坑是少走弯路。很多新手习惯直接敲node app.js但项目一多就会忘到底用哪个命令启动。更好的习惯是在package.json的scripts字段里配置命令{ name: node-learn, version: 1.0.0, main: app.js, scripts: { start: node app.js, dev: node --watch app.js }, type: commonjs }配置之后运行npm start就能启动程序开发时运行npm run dev就能带热重载启动。这样做的好处是命令统一、有迹可循以后把项目交给别人时对方只要看package.json就知道怎么启动。这个习惯我从很早就开始养成现在每个项目都这么干。我自己在带新手入门时最常说的一句话是先别急着背API把从写文件到跑起来的流程多走几遍很多概念自然就通了。Node.js的学习路径很平缓安装环境、跑通第一个程序、理解模块系统、会看报错调试这四个节点走完就已经具备继续往下深挖的底气了。接下来可以根据兴趣挑方向比如用express写Web接口、用fs做文件批处理工具、用child_process执行系统命令每条路都够你研究一阵子。先把这个从0到1的过程扎扎实实走完后面的路会越来越顺。