Node.js 不是一门新语言也不是某个装好看的开发工具它只是让 JavaScript 可以脱离浏览器、直接在电脑上运行的运行时环境。很多人第一次接触它是因为要写 Web 后端、做前端构建工具或者想在本地快速搭一个接口服务。这篇文章目标很直接把 Node.js 装好、把命令行脚本跑通、再写出并启动一个真正的 Web 应用。内容围绕日常最常见的安装方式、版本管理、简单服务和调试部署展开不引入复杂前端框架适合零基础、刚看完 JavaScript 基础、以及在安装阶段被各种报错卡住的人。在往下看之前先说明一个判断新手学 Node.js最容易卡住的不是语法而是“不知道装哪个版本”“npm 命令失效”“端口被占用”“代码能启动但浏览器访问不了”。这些问题解决掉后面写业务代码会顺畅很多。下面按实际学习顺序拆开讲。1. 开始之前先把 Node.js 解决什么问题说清楚1.1 Node.js 到底是什么不是谁的一次性工具很多人会问“Node.js 是干什么的”最简单理解是浏览器里的 JavaScript 只能操作页面和发请求但 Node.js 让 JavaScript 能读写文件、访问网络、监听端口、启动进程。它把 JavaScript 从“页面脚本”变成了“能写服务器程序的通用语言”。Node.js 底层用的是 Chrome 的 V8 引擎这也是它速度快的原因之一。它还采用事件驱动、非阻塞 I/O 的设计简单说就是处理多个请求时不会傻等前面的任务结束再开始下一个。这种特性很适合接口服务、聊天类实时应用、数据中转这类场景。但新手先别过度关心底层。你只需要记住三层关系Node.js负责运行 JavaScript 代码。npmNode.js 自带的包管理器用来安装第三方库。Web 应用用 Node.js 写出来的 HTTP 服务浏览器能访问。1.2 学 Node.js 最实际的应用场景是什么第一个场景是写后端接口。前端页面需要数据后端提供/api/user这样的地址Node.js 可以在里面查数据库、做权限校验、返回 JSON 数据。这类服务上手快逻辑清晰。第二个场景是前端工程化。现在很多前端项目在开发时需要启动本地服务、编译代码、打包资源。这些工具链底层大量依赖 Node.js。就算你只是写 Vue 或 React电脑里也大概率要装 Node.js。第三个场景是写命令行工具。比如批量重命名文件、抓取页面信息、同步目录、生成报表。用 Node.js 写命令行程序比很多脚本语言更直观而且有丰富的 npm 包可以直接用。第四个场景是实时类应用。在线聊天、协同编辑、消息推送这类需要服务端主动往客户端推数据的场景Node.js 的长连接能力是它经常被选中的原因。1.3 学习之前需要有哪些前置基础不需要会“后端”但最好先知道 JavaScript 的变量、函数、条件语句、循环和对象。不用精通能看懂、能改就行。因为这篇文章里的示例都很短核心是让程序跑起来不是讲 JavaScript 语法全集。另外一件事要提前接受之后敲命令不是靠图形界面而是打开命令行工具。Windows 上可以用 PowerShell 或 CMDmacOS 上叫终端Linux 发行版各有终端程序。所有命令都在这个窗口里执行。2. 安装 Node.js版本选择、下载、验证2.1 先定版本策略直接装还是用版本管理工具安装 Node.js 的第一步不是无脑下载最新版而是先决定版本策略。Node.js 官方会同时维护多个版本线主线版本更新快、功能新但可能存在兼容风险备用版本更稳定社区插件和教程覆盖也更全。如果只是学习这篇文章里的内容直接用稳定版通常够用。如果你电脑里已经有好几个项目或者以后要同时维护老项目和新项目建议用 nvm 这类版本管理工具。先安装 nvm再由 nvm 安装 Node.js后面可以随时切换版本。这样能避免“老项目跑不起来”“新版本要求太高”这类问题。我的建议是第一次学直接装稳定版先跑起来。熟悉之后再考虑 nvm。2.2 Windows 环境完整安装流程在 Windows 上安装最稳妥的方式是去官网下载安装包。搜索 Node.js 官网时注意不要进到第三方下载站。官网首页会列出 LTS 和 Current 两个版本新手优先选 LTS。安装包下载完成后按提示下一步即可。有两个地方需要留意安装目录尽量不要带中文和空格默认路径通常没问题。安装过程中建议把“Add to PATH”勾选上否则后续命令会提示找不到 node。安装结束后重新打开一个命令行窗口输入node -v。正常会打印出版本号比如v20.x.x。再输入npm -v会打印 npm 的版本号。两个命令都正常就说明 Node.js 和 npm 都安装成功。2.3 macOS 和 Linux 下的安装差异macOS 可以下载官方 pkg 安装包也可以用 Homebrew 安装。如果你机器里已经有 Homebrew运行一条安装命令就行。Linux 用户可以用发行版自带的包管理器但有些发行版仓库里的 Node.js 版本偏旧建议优先用 nvm 安装指定版本。这里不展开每个发行版的具体命令因为版本更新较快。你只要记住一条原则能用官方安装包或 nvm就尽量不用第三方脚本。安装步骤里如果要求输入管理员密码或做额外配置留意一下来源。2.4 安装完成后除了看版本号还要验证什么很多新手以为node -v能打印版本就结束了。实际上还要确认两件事。第一件是确认 node 命令从哪里来。Windows 上输入where nodemacOS 和 Linux 输入which node可以看到可执行文件路径。如果路径和你安装目录不一致说明 PATH 环境变量可能还有旧版本干扰。第二件是写一个最小脚本测试运行环境。在任意目录新建一个test.js写console.log(hello node);然后在命令行里执行node test.js能输出hello node说明 Node.js 不只是装上了还能正常加载文件。这一步能过滤掉很多“安装了但运行环境有问题”的隐藏故障。2.5 安装阶段三个常见报错路径、运行库、旧系统兼容新手报错集中在三个地方。第一种输入node -v提示“node 不是内部或外部命令”。这通常是 PATH 没有生效或者安装时没有勾选自动加 PATH。可以重新打开终端再不行就手动把 Node 安装目录加到 PATH 里。第二种安装过程提示缺少 Visual C 运行库。Node.js 安装包依赖微软的一些基础运行库个别精简版系统会缺。直接下载并安装对应的运行库再重试通常能解决。第三种旧电脑或旧系统。官方新版本可能已经放弃对某些旧系统的支持安装时报兼容性错误。这种情况下不要硬试最新版应该查找当前电脑系统能支持的最高版本线安装对应版本。3. 用 nvm 管理版本切换报错和旧系统边界3.1 为什么建议现在就把 nvm 装上很多人一个项目用到老Node.js 版本常年不变直到新项目启动时才发现工具链要求更高版本。这个时候再迁移项目、切换环境成本很高。nvm 解决的核心问题就是多版本共存。它可以让你在同一个命令行窗口里快速切换 Node.js 版本而不需要反复卸载安装。你负责不同项目时可以每个项目记录自己的 Node.js 版本要求项目目录里做好说明换台电脑或后面接手的人一看就知道该用哪个版本。如果你只是练手后面几天都用不上版本切换那先不装也行。但如果你是长期写 Node.js建议安装包和 nvm 至少要有一个用过。3.2 nvm 的常用操作不需要记很多安装 nvm 后常用命令其实只有几个nvm install 版本号安装指定版本。nvm use 版本号切换当前命令行使用的版本。nvm ls查看本地所有已安装版本。nvm ls-remote查看远端可安装版本列表。示例nvm install 20 nvm use 20 node -v注意Windows 上的 nvm 和 macOS/Linux 上的 nvm 虽然命令名字一样但安装方式不同。如果你搜索安装教程看到明显不同步骤先确认你当前系统是哪个。macOS 和 Linux 常用的是脚本安装Windows 上常用的是 nvm-windows 安装包。3.3 切换版本后 node 命令消失怎么办版本切换最常见的问题是执行nvm use 20后提示切换成功但输入node -v还是旧版本或者直接提示找不到 node。这种问题先别急着怀疑 nvm 坏了。第一步关掉当前终端窗口重新打开一个让环境变量重新加载。第二步用nvm ls查看当前生效版本确认是不是存在软链没有更新。第三步检查是否在管理员权限的窗口操作。Windows 上如果终端权限不一致切换可能会失败。另一个常见现象是输入某个版本号时提示error installing x.x.x: node.js vx.x.x is not yet released or is not available。这不是电脑坏了而是你拼错了版本号或者远端版本列表还没刷新。先用nvm ls-remote确认可用的版本号再安装。3.4 旧电脑和旧系统的边界要提前确认如果你的电脑还是 Win7或系统版本太老需要降低预期。新版 Node.js 很可能在安装阶段就提示不支持甚至装上了运行也会报错。处理方式是先确认系统是否真的无法兼容再回头找一个旧版本线安装。不要为了强行使用新版去改系统、绕过检测这样后续问题很多。学习用途的话能跑通基本语法、HTTP 服务和 npm 安装就足够验证原理了。4. 从命令行脚本开始理解 node 和 npm 的配合4.1 新建项目和 package.json 的关系很多初学者会犯一个错误把代码文件乱放没有一个项目目录。Node.js 项目通常是一个独立目录里面会有代码文件和一个package.json。package.json是项目的“身份证”记录项目名称、版本、依赖库、启动命令等信息。你可以手动创建也可以使用命令生成npm init -y执行后目录下会出现一个package.json里面包含默认配置。后面安装第三方包时依赖信息也会自动写进这个文件。项目复制到别处时只需要保留代码和package.json再执行npm install就能把依赖重新装回来。4.2 第一个脚本用 node 直接运行文件在项目目录下创建hello.jsconsole.log(hello node); console.log(process.argv);命令行执行node hello.js第二行会打印一个数组数组里前两个元素是 node 可执行文件的路径和你脚本的路径后续元素是你传入的命令行参数。传参示例node hello.js hello world输出的数组末尾会多出hello和world。这个机制在写命令行工具时很常用。4.3 在脚本里读取文件理解 require 和模块Node.js 自带一组核心模块不需要安装。最常用的是fs和path。const fs require(fs); const path require(path); const filePath path.join(__dirname, data.txt); const content fs.readFileSync(filePath, utf-8); console.log(content);这段代码先引入fs模块再读取当前目录下的data.txt。如果你在项目目录下准备一个data.txt执行node file.js后就能看到文件内容。这里有一个关键概念require是 Node.js 里引入模块的方式。第三方 npm 包也是用它加载比如后面会用到的express。4.4 用环境变量控制脚本行为脚本写死了端口和路径部署时会很麻烦。Node.js 提供process.env读取环境变量const port process.env.PORT || 3000; console.log(当前端口是, port);命令行执行node env.js会输出3000。如果先用PORT8080 node env.js再执行就会输出8080。Windows 下临时设置环境变量的写法略有不同但理解process.env这个机制就足够了。5. 用内置 http 模块写出第一个 Web 应用5.1 最小 HTTP 服务器浏览器能直接访问前面几步都是在命令行里运行脚本。现在开始写 Web 应用。Node.js 自带http模块不需要安装第三方库就能启动一个 HTTP 服务。新建server.jsconst http require(http); const server http.createServer((req, res) { res.end(Hello World); }); server.listen(3000, () { console.log(server running at http://127.0.0.1:3000); });命令行执行node server.js打开浏览器访问http://127.0.0.1:3000页面显示Hello World。这个示例虽然短但包含了一个 Web 应用必须具备的三个部分创建服务器、处理请求、监听端口。5.2 根据 URL 返回不同内容真实 Web 应用不可能对任何地址都返回同一句话。先用req.url判断路径const http require(http); const server http.createServer((req, res) { if (req.url /) { res.end(Home); } else if (req.url /about) { res.end(About); } else { res.statusCode 404; res.end(Not Found); } }); server.listen(3000);这里能看到一个最简单但非常关键的思路路由本质上就是“根据请求地址做不同处理”。返回 JSON 数据时需要设置响应头const data JSON.stringify({ name: node, type: runtime }); res.writeHead(200, { Content-Type: application/json }); res.end(data);5.3 端口被占用是新手最先遇到的启动问题启动服务器之后如果再执行一次node server.js大概率会看到EADDRINUSE错误。意思是端口 3000 已经被上一个进程占用。处理顺序是先找到占用端口的进程再选择停掉它或换端口。不要一启动报错就去改代码。Windows 上可以用netstat -ano | findstr :3000看到进程 ID 后在任务管理器里确认并结束。macOS 和 Linux 可以用lsof -i :3000查看占用进程。如果只是开发调试更简单的办法是换一个端口比如server.listen(3001)。但如果是正式部署端口被占说明服务管理方式不规范要系统排查。6. 用 Express 把 Web 应用做成正式项目的样子6.1 为什么有了 http 模块还要用 Express内置http模块能跑通最小应用但代码变多之后很吃力。比如要处理查询参数、解析请求体、区分 POST 和 GET、设置各种响应头手写判断会越来越乱。Express 是 Node.js 生态里最常见的 Web 框架它不改变 Node.js 的底层能力只是把常用操作封装成更简洁的接口。新手不需要等完全理解内置http模块再学 Express两者可以并行。安装命令npm install express执行后node_modules目录会出现依赖文件package.json里也会多出一条express依赖。6.2 Express 最小服务怎么写const express require(express); const app express(); const port 3000; app.get(/, (req, res) { res.send(Hello Express); }); app.listen(port, () { console.log(server running at http://127.0.0.1:${port}); });执行node app.js浏览器访问http://127.0.0.1:3000效果和之前类似但代码结构更清晰。这时你会注意到app.get负责 GET 请求第一个参数是路径第二个参数是处理函数。6.3 路由参数、查询参数和静态文件业务中常见的是拿用户 ID 查详情。Express 支持路由参数app.get(/user/:id, (req, res) { res.json({ id: req.params.id }); });访问http://127.0.0.1:3000/user/123返回 JSON 数据。req.params.id就是路径里的123。查询参数又是另一回事。比如http://127.0.0.1:3000/search?keywordnode要用req.query.keyword获取。静态文件也很常用。项目里放一个public目录里面是 HTML、CSS、图片然后加一行app.use(express.static(public));再访问http://127.0.0.1:3000/index.html就能直接看到页面。这个功能对初学者非常友好因为你不需要手动处理文件流。6.4 中间件从请求到响应之间的一层层处理中间件是 Express 里最需要理解的概念但没有想象中难。它本质就是“在请求到达路由之前先做几层处理”。比如接收 JSON 请求体app.use(express.json()); app.post(/api/data, (req, res) { res.json({ received: req.body }); });没有express.json()req.body会是空对象。用它之后客户端传来的 JSON 数据就能被解析。再比如写一个简单日志中间件app.use((req, res, next) { console.log(req.method, req.url); next(); });这里next表示处理完这层继续向下执行。中间件的顺序很关键一般把公共中间件写在路由之前。7. 运行调试与部署从本地跑通到长期使用7.1 本地调试先看这三个地方不少新手问“为什么浏览器打不开”其实不是代码问题而是不会看运行状态。本地调试时我一般先看三处。第一处是命令行窗口的报错。红色字体通常说明代码语法错误、模块找不到、端口被占用或依赖缺失。第二处是终端里打印的启动日志。比如server running at ...有没有出现。没出现多半代表服务没启动成功。第三处是请求是否到达服务器。在处理函数里加一行console.log(req.url)浏览器访问后终端有没有打印这个地址。没打印说明请求可能没到这个服务或者端口不对。7.2 用 nodemon 减少手动重启修改代码后Node.js 默认不会自动生效需要手动停止进程再重新执行。开发时反复重启很影响手感可以用 nodemon。安装和运行npm install -g nodemon nodemon app.js也可以不全局安装直接用npx nodemon app.js。更正规的方式是在package.json里配置脚本scripts: { dev: nodemon app.js, start: node app.js }之后执行npm run dev启动开发模式修改代码保存后服务会自动重启。7.3 部署前的基本检查清单本地能跑通不代表部署到服务器上没问题。我建议至少检查四件事。第一监听地址。正式环境要让服务对外可访问可以监听0.0.0.0但本地开发时建议用127.0.0.1避免暴露到局域网。第二环境变量。端口、数据库地址、密钥等不要硬编码在代码里用process.env读取。第三进程管理。直接执行node app.js一旦进程退出服务就停了。正式环境要用进程管理工具或容器方案保证服务崩溃后能自动拉起。第四日志。至少记录请求日志和错误日志而不是只打印在终端。出了问题日志是最直接的排查入口。7.4 用进程管理器保持服务长期运行常见的进程管理工具是 PM2。基本工作流程是先在项目目录安装依赖然后用 PM2 启动。pm2 start app.js --name my-app pm2 logs pm2 restart my-app pm2 stop my-appPM2 启动后即使终端关闭服务也会继续运行。它还会自动重启崩溃进程非常省心。由于不同版本命令细节有差异使用前先查看对应文档。8. 高频报错速查表与接下来一周的练习路线8.1 安装阶段问题速查表我把日常看到最多的报错整理成一张表方便你直接对照现象常见原因优先排查顺序node 不是内部或外部命令PATH 未生效重开终端检查安装目录手动加 PATHnpm 不是内部或外部命令npm 未随 Node.js 安装查看安装日志重装 Node.js检查 PATH安装时提示缺少 C 运行库精简系统缺基础组件安装对应运行库关掉杀毒软件再重试卸载报错 2053残留文件或注册表问题清理安装目录删除残留配置用官方卸载工具安装某个版本提示 not released版本号错误或列表未刷新用 nvm ls-remote 查可用版本重新安装命令找不到 node 但已安装节点版本未生效检查 nvm ls重启终端用 nvm use 指定版本8.2 npm 安装依赖失败时先做什么npm 安装失败不要第一时间怀疑电脑坏了。先做四件事。第一看完整报错。npm 会告诉你是不是网络超时、文件名错误、权限不足或包不存在。第二检查 Node.js 和 npm 版本。某些包要求 Node.js 新版某些老项目又依赖旧版。npm -v和node -v先打出来看一眼。第三检查项目目录中的package.json是否完整。缺失或重复的依赖项也可能导致安装中断。第四如果你处在一个特殊网络环境里可以尝试切换公共 npm 镜像源或者用npm cache verify清理缓存后再试。这里不推荐遇到问题就无脑重建先把日志看清楚。8.3 版本切换报错时按什么顺序排查版本切换报错最容易误导人的地方是“提示成功但实际没变”。排查顺序可以固定下来重新打开命令行窗口确认环境变量已重新加载。运行nvm ls查看当前生效版本是哪一个。运行node -v确认实际的 node 命令路径是否指向 nvm 管理的目录。如果提示某个版本未安装直接重新执行安装命令。如果系统里同时装有其他 Node.js 安装包先卸载或移除 PATH 里的旧路径避免冲突。很多时候不是 nvm 不行而是系统里存在两套 Node.js导致命令优先级互相干扰。8.4 接下来一周怎么继续练安装跑通、第一个 Web 应用启动之后下一步不是立刻学各种框架而是把基础能力练扎实。我给一个很朴素的路线前两到三天用 Node.js 写文件操作和简单命令行工具。比如批量重命名文件、读取一个 JSON 配置文件、把文本文件转成 CSV。中间两天把文章里的 HTTP 服务改成一个小接口。做一个待办事项列表接口支持新增、查询、删除数据先存在内存里或 JSON 文件里。先不接数据库降低复杂度。第六天开始试着用 Express 写一个带静态页面的小系统。比如留言板前端一个表单后端接收数据保存到本地 JSON 文件再展示出来。第七天把服务部署到一台远程开发机或服务器上用进程管理工具保持服务运行。能跑通这一步你就从“会写 Demo”变成了“能把服务跑在真实环境里”。这个阶段不要追求功能大而全优先保证每次写完都能启动、能访问、能通过日志定位问题。Node.js 的入门核心不是背诵 API而是建立“写代码 - 启动服务 - 看日志 - 改代码”的循环。一个小时内装好环境、跑通第一个 Web 应用完全来得及真正要花时间的是后面反复用这个循环去练手。