最近很多刚接触后端的朋友问我JavaScript 不是只能写网页吗为什么还能写接口、连数据库、跑服务Node.js 到底是干什么的这篇文章我就带你用最快的方式把 Node.js 从安装到写出第一个能访问的 Web 应用完整跑通。无论是零基础入门还是已经写过前端代码、想往后端方向扩展这套教程都适用。本文会先讲清楚 Node.js 的核心概念再进入环境安装和代码实战最后整理一份高频报错排查清单整个过程按一小时节奏安排不需要你提前掌握后端知识。1. Node.js 是什么为什么它能让 JavaScript 写后端1.1 Node.js 的通俗解释简单说Node.js 是一个“让 JavaScript 脱离浏览器也能运行”的运行时环境。它内部使用了 Chrome 浏览器的 V8 JavaScript 引擎把 JavaScript 解释执行成了机器码使得 JavaScript 可以在服务器、命令行工具、桌面工具等场景中运行。以前我们写前端页面JavaScript 只能在浏览器里操作 DOM、绑定事件、发送请求一旦关掉页面代码就没了。而 Node.js 给 JavaScript 增加了文件读写、网络通信、进程管理、系统操作等能力这些能力在浏览器里是被限制的但在服务端却是基础能力。于是前端开发者可以用同一门语言继续写后端服务这也是 Node.js 能快速流行的根本原因。1.2 Node.js 解决了什么问题Node.js 最大的特点是事件驱动和非阻塞 I/O。传统后端在处理文件读取、数据库查询这类耗时操作时通常是一个请求占住一个线程等操作完成再返回。而 Node.js 采用异步回调机制遇到耗时操作会先挂起继续处理下一个请求等操作完成后再通过事件循环回调结果。对于 I/O 密集型的业务比如 REST API、聊天服务、数据推送、实时通信这种方式在单线程下也能支撑很高的并发量。当然Node.js 并非万能。如果是 CPU 密集型场景比如图像处理、复杂计算、音视频转码Node.js 的优势就不明显甚至可能因为阻塞事件循环而变慢。选型时需要结合业务场景。1.3 Node.js 的典型应用场景Node.js 最常用的场景包括Web API 服务使用 Express、Koa、NestJS 等框架开发后端接口。实时通信程序聊天室、协作编辑、在线游戏服务端。命令行工具很多前端构建工具比如 Webpack、Vite、Gulp 都基于 Node.js 运行。前端工程化编译、打包、代码检查、自动化测试脚本。物联网与嵌入式配合串口、传感器数据采集和处理。爬虫与自动化脚本用 Node.js 写脚本抓取数据、处理文件、操作浏览器。对于刚入门的人来说最容易理解的应用就是“用 Node.js 写一个 Web 服务让浏览器或其他设备通过 HTTP 访问到我们提供的页面或接口”。这篇文章的实战环节就是围绕这个目标展开的。2. 环境准备Node.js 安装与版本管理2.1 安装前需要理解的版本概念Node.js 的版本分为 LTS 和 Current 两类。LTS 是长期维护版本稳定性和兼容性优先适合生产环境Current 是当前特性版本会包含较新的 JavaScript 语法和 API但迭代较快不建议在重要项目中使用。刚入门时不需要追求最新版本装一个 LTS 版本就够了。很多教程里出现 “error installing 24.19.0: node.js v24.19.0 is not yet released or is not available” 这类报错多半是因为在版本管理工具里指定了一个并不存在的版本号。版本号必须以 Node.js 官网实际发布的为准不需要手动指定过新的版本。开发中可以同时安装多个 Node.js 版本通过版本管理工具来回切换。常见的工具是 nvmLinux/macOS和 nvm-windows。这样当不同项目需要不同 Node 版本时不需要反复卸载安装。2.2 Windows 系统安装 Node.jsWindows 有两种常见安装方式。第一种是直接去 Node.js 官网下载 Windows Installer.msi安装包双击安装。这个方式最直观安装程序会自动配置环境变量。安装完成后需要重新打开一个命令行窗口因为新加的环境变量不会自动生效到已经打开的终端里。第二种是安装 nvm-windows 来管理多版本。安装 nvm-windows 后可以通过命令安装和切换不同版本的 Node.js。示例命令如下# 查看 nvm 是否安装成功 nvm version # 查看本机已安装的 Node.js 版本列表 nvm list # 安装指定版本例如 22.13.1 nvm install 22.13.1 # 切换到指定版本 nvm use 22.13.1如果你在命令行里看到类似下面这种输出说明 nvm 正在正常下载安装包C:\Users\Administratornvm install 22.13.1 Downloading node.js version 22.13.1... Complete安装完成后执行node -v能看到对应版本号就说明切换成功。需要特别提醒的是如果电脑还是 Windows 7较新的 Node.js 版本已经不支持了需要安装适配旧系统的历史版本。遇到这种情况应先在官网确认该系统支持的版本范围不要盲目下载最新版本。2.3 macOS 与 Linux 安装方式macOS 上推荐使用 Homebrew 安装brew install nodeLinux 系统使用系统包管理器直接安装时比如sudo apt update sudo apt install nodejs npm这种方式通常安装的是发行版软件源里的包版本可能比较旧。更推荐使用 nvm 或 NodeSource 提供的安装源来安装指定版本。nvm 安装后同样通过nvm install和nvm use管理版本。无论使用哪种操作系统安装完成后都可以用下面的命令验证环境node -v npm -v能正常输出版本号说明安装成功。2.4npm与国内镜像源配置npm 是 Node.js 自带的包管理工具全称 Node Package Manager。它负责下载、安装、管理项目依赖的第三方模块。安装完 Node.js 后npm 也会一起装好。在默认情况下npm 从官方仓库下载包。如果下载速度慢可以根据自己的网络环境配置镜像源。这里介绍配置国内镜像的方法仅作为常规技术操作不会涉及任何网络代理内容# 查看当前 npm 镜像地址 npm config get registry # 修改为国内镜像源 npm config set registry https://registry.npmmirror.com配置完成后再次执行npm config get registry能看到地址已经变化。之后安装依赖包的速度会有明显提升。2.5IDE与终端准备编写 JavaScript 代码不需要复杂的 IDE一个文本编辑器加命令行就能运行。不过项目代码多了以后推荐使用 VS Code 这类现代编辑器。VS Code 自带终端可以在编辑器内部直接执行 npm 命令查看代码报错也更方便。本文的示例不需要额外安装插件所有命令都能直接在终端执行。3. 核心概念速览模块、npm 与 package.json在写第一个 Web 应用之前先理解几个最基础的概念。它们是后续所有 Node.js 项目的地基。3.1CommonJS模块系统Node.js 早期采用 CommonJS 规范来组织代码。每个文件可以看作一个模块通过require引入其他模块通过module.exports导出本模块内容。最简单的导入导出示例// 文件路径greeting.js function sayHello(name) { return Hello, name; } module.exports { sayHello };// 文件路径app.js const greeting require(./greeting); console.log(greeting.sayHello(CSDN));当你在终端执行node app.js时会输出Hello, CSDN这种模块化方式最大的好处是把代码拆分到不同文件职责边界清晰方便维护和复用。3.2npm初始化与 package.json在开始一个 Node.js 项目时通常会在项目根目录执行npm init -y这个命令会生成一个package.json文件里面记录了项目名称、版本、依赖包、脚本命令等信息。package.json是项目的心脏后续安装的依赖都会记录到这里。一个典型的package.json结构如下{ name: my-node-app, version: 1.0.0, description: 我的第一个 Node.js Web 应用, main: app.js, scripts: { start: node app.js }, author: , license: ISC, dependencies: { express: ^4.19.2 } }其中dependencies表示生产环境依赖devDependencies表示只在开发阶段需要的依赖。npm install express会把 express 安装到当前项目并写入 dependenciesnpm install -D nodemon会写入 devDependencies。3.3npm常用命令下面这些命令是使用 Node.js 过程中最频繁的命令作用npm init -y初始化项目并生成 package.jsonnpm install 包名安装依赖到当前项目npm install -D 包名安装开发依赖npm install -g 包名全局安装命令行工具npm uninstall 包名卸载依赖npm run xxx执行 package.json scripts 中定义的脚本npm list --depth0查看当前项目顶层依赖对于初学者来说最常混淆的是“全局安装”和“本地安装”。全局安装适合那些需要在任何目录都能使用的命令行工具比如npm install -g nodemon本地安装则适合项目运行所依赖的库比如 express。一般项目依赖都应该在项目目录中本地安装不要全局安装。4. 完整实战从零写出第一个 Web 应用接下来进入核心部分。我们会分两步完成 Web 应用第一步使用 Node.js 自带的http模块写一个极简 HTTP 服务让你理解 Web 服务的最底层逻辑第二步使用 Express 框架写一个更结构化的 Web 应用支持路由、JSON 接口和静态文件访问。4.1 创建项目结构先在命令行中创建一个项目目录并进入mkdir my-node-app cd my-node-app npm init -y建议项目目录名使用英文小写不要包含中文和空格因为 npm 对包名有严格限制。初始化后目录下会生成package.json文件。最终目录结构如下my-node-app ├── package.json ├── app.js └── public └── index.html其中app.js是项目主文件public目录用于存放静态资源。4.2 使用 Node.js 内置 http 模块创建服务器先不引入任何第三方依赖用 Node.js 自带的http模块写一个最简单的 HTTP 服务器。新建app.js输入以下代码// 文件路径app.js const http require(http); const server http.createServer((req, res) { res.writeHead(200, { Content-Type: text/plain; charsetutf-8 }); res.end(Hello, Node.js!); }); const port 3000; server.listen(port, () { console.log(服务器已启动http://localhost:${port}); });这段代码的作用是创建一个 HTTP 服务器每当有浏览器请求到来服务器返回一段纯文本“Hello, Node.js!”。server.listen(port, callback)让服务器监听 3000 端口启动成功后会在终端输出提示。在终端运行node app.js终端会显示服务器已启动http://localhost:3000然后打开浏览器访问http://localhost:3000页面会显示“Hello, Node.js!”。如果浏览器访问不了可以检查端口是否被占用或者确认服务器进程是否还在运行。通过这个例子可以看到一个 Web 应用本质上就是一个处理 HTTP 请求的服务端程序。http.createServer中传入的回调函数接收两个参数req表示客户端请求res表示服务器响应。后续所有 Web 框架都是在这个基础上做了封装和增强。4.3 使用 Express 构建更完整的 Web 应用原生http模块虽然能启动服务但写接口时非常繁琐。接下来引入 Express 框架它是 Node.js 生态中最流行的 Web 框架之一提供了路由、中间件、静态文件托管、请求参数解析等能力。先停止当前正在运行的 Node 进程在终端按 Ctrl C然后安装 Expressnpm install express安装完成后重写app.js// 文件路径app.js const express require(express); const path require(path); const app express(); const port 3000; // 解析 JSON 请求体 app.use(express.json()); // 首页路由 app.get(/, (req, res) { res.send(欢迎访问我的第一个 Node.js Web 应用); }); // GET 接口示例 app.get(/api/info, (req, res) { res.json({ code: 0, message: success, data: { name: My Node App, version: 1.0.0 } }); }); // POST 接口示例 app.post(/api/echo, (req, res) { const body req.body || {}; res.json({ code: 0, message: success, data: body }); }); // 静态资源目录 app.use(express.static(path.join(__dirname, public))); app.listen(port, () { console.log(服务器已启动http://localhost:${port}); });下面逐段解释这段代码express()创建了一个应用实例。app.use(express.json())注册了 JSON 解析中间件这样POST请求携带的 JSON 数据会被解析到req.body中。app.get(/, handler)定义了首页 GET 请求的路由处理函数。app.get(/api/info, handler)定义了一个返回 JSON 数据的接口res.json会自动设置Content-Type为application/json。app.post(/api/echo, handler)定义了一个接收 JSON 数据并原样返回的接口。express.static让public目录下的文件可以直接通过 URL 访问。4.4 添加静态页面在项目下新建public目录和index.html文件mkdir public然后创建public/index.html!-- 文件路径public/index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的 Node.js Web 应用/title /head body h1我的第一个 Node.js Web 应用/h1 p这个页面由 Express 静态服务提供。/p button onclickloadInfo()点击获取接口数据/button pre idresult/pre script async function loadInfo() { const response await fetch(/api/info); const data await response.json(); document.getElementById(result).textContent JSON.stringify(data, null, 2); } /script /body /html运行服务器node app.js这时访问http://localhost:3000会优先展示public/index.html因为express.static中间件的作用就是直接返回静态文件。访问http://localhost:3000/api/info会得到 JSON 数据。点击页面上的按钮前端 JavaScript 会请求接口并在页面显示响应结果。4.5 用 nodemon 实现开发时自动重启每次修改代码后手动重启服务比较麻烦。可以使用nodemon来做自动重启。安装并配置npm install -D nodemon然后修改package.json中的scripts字段{ scripts: { start: node app.js, dev: nodemon app.js } }之后开发阶段用npm run dev启动服务每次保存文件nodemon会检测到变更并自动重启。验证一个功能是否可用可以打开浏览器访问对应的 URL也可以使用curl命令curl http://localhost:3000/api/info预期会输出类似内容{code:0,message:success,data:{name:My Node App,version:1.0.0}}到这里你已经在本地跑起来了一个基于 Express 的 Web 应用它包含页面路由、JSON 接口、静态资源服务和前端请求接口的完整闭环。4.6 结果说明与下一步验证此时项目里已经出现了node_modules目录这是 npm 安装依赖后生成的真实文件目录。它会很大不要手动改动它也不要提交到 Git 仓库。在项目中再创建一个.gitignore文件写入以下内容node_modules/这样用 Git 管理项目时依赖目录会被忽略。别人拿到项目后执行npm install就能根据package.json恢复所有依赖。5. 常见问题与排查思路新手在安装和运行 Node.js 项目时会遇到不少环境相关问题。这里整理一份高频问题清单覆盖从安装到运行的大部分典型报错。问题现象常见原因解决思路node不是内部或外部命令Node.js 未安装、环境变量未配置、安装后未重启终端重新安装或手动配置 PATH重新打开命令行窗口nvm install 版本号报 “not yet released or is not available”指定的版本号不存在或尚未发布查看可用版本后重新安装GUI 工具提示 “node.js not found (please save below and restart)”第三方工具配置时无法找到 node 可执行文件检查 node 是否已加入 PATH保存配置文件并重启工具端口报错EADDRINUSE3000 端口已被其他进程占用更换端口或找到并结束占用端口的进程终端中文乱码控制台编码与项目输出编码不一致Windows 可在命令行执行chcp 65001切换到 UTF-8npm install速度很慢默认源连接慢按实际情况配置镜像源安装依赖时出现ERESOLVE依赖冲突依赖版本冲突常见于 npm 高版本升级依赖、检查重复依赖或使用--legacy-peer-depsWindows 7 装不上新版本新版 Node.js 不支持旧系统下载适配旧系统的历史版本浏览器访问localhost:3000无响应服务未启动、端口错误、防火墙拦截查看终端是否输出启动成功日志检查端口更改为其他值node_modules被误删后项目无法启动依赖缺失在项目目录重新执行npm install下面挑几个高频场景展开说明。5.1 安装后提示“node 不是内部或外部命令”这个报错在 Windows 上最常见。安装完成后需要重启命令行窗口让新配置的环境变量生效。如果重启后仍然报错打开系统环境变量设置检查Path变量里是否包含了 Node.js 的安装目录。没有的话手动添加 Node.js 的安装路径例如C:\Program Files\nodejs\。使用 nvm-windows 管理版本时执行nvm use 22.13.1后如果看不到 node 命令先执行nvm list确认版本确实已经安装然后重新打开终端。5.2 nvm 安装指定版本时报错提示版本不存在如果你执行了类似nvm install 24.19.0的命令但 Node.js 官方并没有发布这个版本就会得到 “not yet released or is not available” 的提示。此时可以查看当前可用版本列表再选择具体版本安装nvm list available安装一个明确存在的 LTS 版本即可。版本选择不要追新稳定优先。5.3 第三方工具提示找不到 Node.js有些图形化界面工具比如低代码工具或自动化脚本工具在安装配置时会要求选择 Node.js 路径。如果提示 “node.js not found (please save below and restart)”说明工具没有在默认环境变量中找到 node可以在工具配置界面手动指定 node 可执行文件的路径保存后重启工具。配置前先执行where nodeWindows或which nodeLinux/macOS拿到实际路径再填入。5.4 端口被占用Express 常见的报错是Error: listen EADDRINUSE: address already in use :::3000这表示 3000 端口已经被另一个进程占用。解决办法有两种一是修改代码里的端口号例如改成 3001二是找出占用端口的进程并结束它。Windows 可以使用netstat -ano | findstr :3000Linux/macOS 可以使用lsof -i:3000找到对应进程 ID 后再决定是否结束进程。生产环境中千万不要随意 kill 未知进程先确认进程归属再操作。6. 最佳实践与工程建议从“能跑通”到“稳定好用”中间还有一段路要走。下面这些建议来自实际工程中的常见规范适合尽早养成习惯。6.1 使用版本管理工具管理 Node.js不要在系统里只装一个 Node.js 然后一直升级。项目多了以后不同项目可能依赖不同的 Node 版本升级一个可能会影响另一个。推荐使用 nvm 或 nvm-windows 管理多版本并在项目文档中明确标注当前项目使用的 Node 版本。团队协作时还可以在项目根目录添加.nvmrc文件记录版本号内容可以直接写版本号比如22.13.1这样团队成员执行nvm use时可以自动切换到对应版本减少环境不一致带来的问题。6.2 依赖管理规范要把node_modules当作缓存目录不要手动修改里面任何文件。所有依赖必须通过npm install 包名安装这样会写入package.json保证别人 clone 项目后可以用一条命令恢复。另一点是区分dependencies和devDependencies。只用于开发阶段的工具比如nodemon应该用-D参数安装。生产环境部署时执行npm install --production就不会安装开发依赖减少不必要的文件。6.3 通过环境变量配置参数端口号、数据库地址、密钥等配置不应该写死在代码里。理想做法是通过环境变量注入代码里提供默认值作为兜底const port process.env.PORT || 3000;这样在本地开发时默认使用 3000 端口部署到服务器后可以通过环境变量覆盖。不同环境的差异由配置管理解决而不是反复改代码再重新部署。6.4 异常处理与进程稳定Node.js 的特点是异步回调多未捕获的异常可能导致进程直接崩溃。在开发阶段可以在入口文件监听未处理异常并打印日志process.on(unhandledRejection, (reason, promise) { console.error(Unhandled Rejection at:, promise, reason:, reason); }); process.on(uncaughtException, (err) { console.error(Uncaught Exception:, err); });但要注意这只是让问题暴露得更容易定位不能替代业务层面的错误捕获。接口业务代码应该使用 try-catch 包裹可能出错的逻辑并在响应中返回合理的错误提示。6.5 生产环境部署建议生产环境中不要使用nodemon启动服务它只适合开发调试。更稳妥的方式是使用进程管理工具比如pm2。它可以守护进程应用崩溃时自动重启还可以管理日志输出。生产上线前还需要注意不要用 root 用户直接运行 Web 服务尽量使用独立低权限账号敏感信息比如数据库密码、密钥不要写进代码仓库应通过环境变量或专门的配置服务管理生产环境错误提示不要返回完整堆栈避免信息泄露。6.6 日志与可观测性console.log用于开发调试很方便但在生产环境中信息太零散。推荐使用日志库比如winston、pino按级别输出日志并区分访问日志和错误日志。使用pm2时也可以配置日志文件输出。一个好的日志体系能大幅降低线上问题排查成本。6.7 保持学习路径清晰入门阶段先把一个简单 Web 服务跑通理解请求和响应的基本流程。接下来按顺序学习 Express 中间件机制、RESTful API 设计、连接数据库、用户认证、部署上线逐步形成完整闭环。如果发现某个知识点反复出错先停下来查基础不要急于抄写完功能就结束。7. 总结与学习路线经过这一小时的实践你已经完成了这些关键步骤理解了 Node.js 作为 JavaScript 运行时环境的基本定位安装了 Node.js 和 npm并通过 nvm 学会了版本管理熟悉了 package.json、模块系统、npm 常用命令用原生 http 模块写出了第一个 HTTP 服务使用 Express 搭建了包含页面、JSON 接口和静态资源的 Web 应用最后还掌握了一套常见报错排查方法。下一步可以尝试改造这个项目增加更多 RESTful 接口把接口数据接入 MySQL 或 MongoDB使用模板引擎渲染页面实现简单的登录注册功能最后把应用部署到云服务器上。建议选择一个你感兴趣的小项目比如待办事项管理工具从设计数据结构开始完整走一遍开发流程。只有亲自动手改代码、跑服务、查报错才能把 Node.js 的知识点真正串起来。如果在后续的安装或运行过程中遇到新问题优先检查版本号、终端是否重启、依赖是否完整安装、端口是否被占用这几类常见原因。把报错信息完整复制到搜索引擎中多数问题都能找到对应解法。这篇文章中的示例代码可以直接复制使用也可以在此基础上扩展成属于你自己的第一个 Node.js 应用。 Node.js入门实战：从安装到创建第一个Web应用
最近很多刚接触后端的朋友问我JavaScript 不是只能写网页吗为什么还能写接口、连数据库、跑服务Node.js 到底是干什么的这篇文章我就带你用最快的方式把 Node.js 从安装到写出第一个能访问的 Web 应用完整跑通。无论是零基础入门还是已经写过前端代码、想往后端方向扩展这套教程都适用。本文会先讲清楚 Node.js 的核心概念再进入环境安装和代码实战最后整理一份高频报错排查清单整个过程按一小时节奏安排不需要你提前掌握后端知识。1. Node.js 是什么为什么它能让 JavaScript 写后端1.1 Node.js 的通俗解释简单说Node.js 是一个“让 JavaScript 脱离浏览器也能运行”的运行时环境。它内部使用了 Chrome 浏览器的 V8 JavaScript 引擎把 JavaScript 解释执行成了机器码使得 JavaScript 可以在服务器、命令行工具、桌面工具等场景中运行。以前我们写前端页面JavaScript 只能在浏览器里操作 DOM、绑定事件、发送请求一旦关掉页面代码就没了。而 Node.js 给 JavaScript 增加了文件读写、网络通信、进程管理、系统操作等能力这些能力在浏览器里是被限制的但在服务端却是基础能力。于是前端开发者可以用同一门语言继续写后端服务这也是 Node.js 能快速流行的根本原因。1.2 Node.js 解决了什么问题Node.js 最大的特点是事件驱动和非阻塞 I/O。传统后端在处理文件读取、数据库查询这类耗时操作时通常是一个请求占住一个线程等操作完成再返回。而 Node.js 采用异步回调机制遇到耗时操作会先挂起继续处理下一个请求等操作完成后再通过事件循环回调结果。对于 I/O 密集型的业务比如 REST API、聊天服务、数据推送、实时通信这种方式在单线程下也能支撑很高的并发量。当然Node.js 并非万能。如果是 CPU 密集型场景比如图像处理、复杂计算、音视频转码Node.js 的优势就不明显甚至可能因为阻塞事件循环而变慢。选型时需要结合业务场景。1.3 Node.js 的典型应用场景Node.js 最常用的场景包括Web API 服务使用 Express、Koa、NestJS 等框架开发后端接口。实时通信程序聊天室、协作编辑、在线游戏服务端。命令行工具很多前端构建工具比如 Webpack、Vite、Gulp 都基于 Node.js 运行。前端工程化编译、打包、代码检查、自动化测试脚本。物联网与嵌入式配合串口、传感器数据采集和处理。爬虫与自动化脚本用 Node.js 写脚本抓取数据、处理文件、操作浏览器。对于刚入门的人来说最容易理解的应用就是“用 Node.js 写一个 Web 服务让浏览器或其他设备通过 HTTP 访问到我们提供的页面或接口”。这篇文章的实战环节就是围绕这个目标展开的。2. 环境准备Node.js 安装与版本管理2.1 安装前需要理解的版本概念Node.js 的版本分为 LTS 和 Current 两类。LTS 是长期维护版本稳定性和兼容性优先适合生产环境Current 是当前特性版本会包含较新的 JavaScript 语法和 API但迭代较快不建议在重要项目中使用。刚入门时不需要追求最新版本装一个 LTS 版本就够了。很多教程里出现 “error installing 24.19.0: node.js v24.19.0 is not yet released or is not available” 这类报错多半是因为在版本管理工具里指定了一个并不存在的版本号。版本号必须以 Node.js 官网实际发布的为准不需要手动指定过新的版本。开发中可以同时安装多个 Node.js 版本通过版本管理工具来回切换。常见的工具是 nvmLinux/macOS和 nvm-windows。这样当不同项目需要不同 Node 版本时不需要反复卸载安装。2.2 Windows 系统安装 Node.jsWindows 有两种常见安装方式。第一种是直接去 Node.js 官网下载 Windows Installer.msi安装包双击安装。这个方式最直观安装程序会自动配置环境变量。安装完成后需要重新打开一个命令行窗口因为新加的环境变量不会自动生效到已经打开的终端里。第二种是安装 nvm-windows 来管理多版本。安装 nvm-windows 后可以通过命令安装和切换不同版本的 Node.js。示例命令如下# 查看 nvm 是否安装成功 nvm version # 查看本机已安装的 Node.js 版本列表 nvm list # 安装指定版本例如 22.13.1 nvm install 22.13.1 # 切换到指定版本 nvm use 22.13.1如果你在命令行里看到类似下面这种输出说明 nvm 正在正常下载安装包C:\Users\Administratornvm install 22.13.1 Downloading node.js version 22.13.1... Complete安装完成后执行node -v能看到对应版本号就说明切换成功。需要特别提醒的是如果电脑还是 Windows 7较新的 Node.js 版本已经不支持了需要安装适配旧系统的历史版本。遇到这种情况应先在官网确认该系统支持的版本范围不要盲目下载最新版本。2.3 macOS 与 Linux 安装方式macOS 上推荐使用 Homebrew 安装brew install nodeLinux 系统使用系统包管理器直接安装时比如sudo apt update sudo apt install nodejs npm这种方式通常安装的是发行版软件源里的包版本可能比较旧。更推荐使用 nvm 或 NodeSource 提供的安装源来安装指定版本。nvm 安装后同样通过nvm install和nvm use管理版本。无论使用哪种操作系统安装完成后都可以用下面的命令验证环境node -v npm -v能正常输出版本号说明安装成功。2.4npm与国内镜像源配置npm 是 Node.js 自带的包管理工具全称 Node Package Manager。它负责下载、安装、管理项目依赖的第三方模块。安装完 Node.js 后npm 也会一起装好。在默认情况下npm 从官方仓库下载包。如果下载速度慢可以根据自己的网络环境配置镜像源。这里介绍配置国内镜像的方法仅作为常规技术操作不会涉及任何网络代理内容# 查看当前 npm 镜像地址 npm config get registry # 修改为国内镜像源 npm config set registry https://registry.npmmirror.com配置完成后再次执行npm config get registry能看到地址已经变化。之后安装依赖包的速度会有明显提升。2.5IDE与终端准备编写 JavaScript 代码不需要复杂的 IDE一个文本编辑器加命令行就能运行。不过项目代码多了以后推荐使用 VS Code 这类现代编辑器。VS Code 自带终端可以在编辑器内部直接执行 npm 命令查看代码报错也更方便。本文的示例不需要额外安装插件所有命令都能直接在终端执行。3. 核心概念速览模块、npm 与 package.json在写第一个 Web 应用之前先理解几个最基础的概念。它们是后续所有 Node.js 项目的地基。3.1CommonJS模块系统Node.js 早期采用 CommonJS 规范来组织代码。每个文件可以看作一个模块通过require引入其他模块通过module.exports导出本模块内容。最简单的导入导出示例// 文件路径greeting.js function sayHello(name) { return Hello, name; } module.exports { sayHello };// 文件路径app.js const greeting require(./greeting); console.log(greeting.sayHello(CSDN));当你在终端执行node app.js时会输出Hello, CSDN这种模块化方式最大的好处是把代码拆分到不同文件职责边界清晰方便维护和复用。3.2npm初始化与 package.json在开始一个 Node.js 项目时通常会在项目根目录执行npm init -y这个命令会生成一个package.json文件里面记录了项目名称、版本、依赖包、脚本命令等信息。package.json是项目的心脏后续安装的依赖都会记录到这里。一个典型的package.json结构如下{ name: my-node-app, version: 1.0.0, description: 我的第一个 Node.js Web 应用, main: app.js, scripts: { start: node app.js }, author: , license: ISC, dependencies: { express: ^4.19.2 } }其中dependencies表示生产环境依赖devDependencies表示只在开发阶段需要的依赖。npm install express会把 express 安装到当前项目并写入 dependenciesnpm install -D nodemon会写入 devDependencies。3.3npm常用命令下面这些命令是使用 Node.js 过程中最频繁的命令作用npm init -y初始化项目并生成 package.jsonnpm install 包名安装依赖到当前项目npm install -D 包名安装开发依赖npm install -g 包名全局安装命令行工具npm uninstall 包名卸载依赖npm run xxx执行 package.json scripts 中定义的脚本npm list --depth0查看当前项目顶层依赖对于初学者来说最常混淆的是“全局安装”和“本地安装”。全局安装适合那些需要在任何目录都能使用的命令行工具比如npm install -g nodemon本地安装则适合项目运行所依赖的库比如 express。一般项目依赖都应该在项目目录中本地安装不要全局安装。4. 完整实战从零写出第一个 Web 应用接下来进入核心部分。我们会分两步完成 Web 应用第一步使用 Node.js 自带的http模块写一个极简 HTTP 服务让你理解 Web 服务的最底层逻辑第二步使用 Express 框架写一个更结构化的 Web 应用支持路由、JSON 接口和静态文件访问。4.1 创建项目结构先在命令行中创建一个项目目录并进入mkdir my-node-app cd my-node-app npm init -y建议项目目录名使用英文小写不要包含中文和空格因为 npm 对包名有严格限制。初始化后目录下会生成package.json文件。最终目录结构如下my-node-app ├── package.json ├── app.js └── public └── index.html其中app.js是项目主文件public目录用于存放静态资源。4.2 使用 Node.js 内置 http 模块创建服务器先不引入任何第三方依赖用 Node.js 自带的http模块写一个最简单的 HTTP 服务器。新建app.js输入以下代码// 文件路径app.js const http require(http); const server http.createServer((req, res) { res.writeHead(200, { Content-Type: text/plain; charsetutf-8 }); res.end(Hello, Node.js!); }); const port 3000; server.listen(port, () { console.log(服务器已启动http://localhost:${port}); });这段代码的作用是创建一个 HTTP 服务器每当有浏览器请求到来服务器返回一段纯文本“Hello, Node.js!”。server.listen(port, callback)让服务器监听 3000 端口启动成功后会在终端输出提示。在终端运行node app.js终端会显示服务器已启动http://localhost:3000然后打开浏览器访问http://localhost:3000页面会显示“Hello, Node.js!”。如果浏览器访问不了可以检查端口是否被占用或者确认服务器进程是否还在运行。通过这个例子可以看到一个 Web 应用本质上就是一个处理 HTTP 请求的服务端程序。http.createServer中传入的回调函数接收两个参数req表示客户端请求res表示服务器响应。后续所有 Web 框架都是在这个基础上做了封装和增强。4.3 使用 Express 构建更完整的 Web 应用原生http模块虽然能启动服务但写接口时非常繁琐。接下来引入 Express 框架它是 Node.js 生态中最流行的 Web 框架之一提供了路由、中间件、静态文件托管、请求参数解析等能力。先停止当前正在运行的 Node 进程在终端按 Ctrl C然后安装 Expressnpm install express安装完成后重写app.js// 文件路径app.js const express require(express); const path require(path); const app express(); const port 3000; // 解析 JSON 请求体 app.use(express.json()); // 首页路由 app.get(/, (req, res) { res.send(欢迎访问我的第一个 Node.js Web 应用); }); // GET 接口示例 app.get(/api/info, (req, res) { res.json({ code: 0, message: success, data: { name: My Node App, version: 1.0.0 } }); }); // POST 接口示例 app.post(/api/echo, (req, res) { const body req.body || {}; res.json({ code: 0, message: success, data: body }); }); // 静态资源目录 app.use(express.static(path.join(__dirname, public))); app.listen(port, () { console.log(服务器已启动http://localhost:${port}); });下面逐段解释这段代码express()创建了一个应用实例。app.use(express.json())注册了 JSON 解析中间件这样POST请求携带的 JSON 数据会被解析到req.body中。app.get(/, handler)定义了首页 GET 请求的路由处理函数。app.get(/api/info, handler)定义了一个返回 JSON 数据的接口res.json会自动设置Content-Type为application/json。app.post(/api/echo, handler)定义了一个接收 JSON 数据并原样返回的接口。express.static让public目录下的文件可以直接通过 URL 访问。4.4 添加静态页面在项目下新建public目录和index.html文件mkdir public然后创建public/index.html!-- 文件路径public/index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的 Node.js Web 应用/title /head body h1我的第一个 Node.js Web 应用/h1 p这个页面由 Express 静态服务提供。/p button onclickloadInfo()点击获取接口数据/button pre idresult/pre script async function loadInfo() { const response await fetch(/api/info); const data await response.json(); document.getElementById(result).textContent JSON.stringify(data, null, 2); } /script /body /html运行服务器node app.js这时访问http://localhost:3000会优先展示public/index.html因为express.static中间件的作用就是直接返回静态文件。访问http://localhost:3000/api/info会得到 JSON 数据。点击页面上的按钮前端 JavaScript 会请求接口并在页面显示响应结果。4.5 用 nodemon 实现开发时自动重启每次修改代码后手动重启服务比较麻烦。可以使用nodemon来做自动重启。安装并配置npm install -D nodemon然后修改package.json中的scripts字段{ scripts: { start: node app.js, dev: nodemon app.js } }之后开发阶段用npm run dev启动服务每次保存文件nodemon会检测到变更并自动重启。验证一个功能是否可用可以打开浏览器访问对应的 URL也可以使用curl命令curl http://localhost:3000/api/info预期会输出类似内容{code:0,message:success,data:{name:My Node App,version:1.0.0}}到这里你已经在本地跑起来了一个基于 Express 的 Web 应用它包含页面路由、JSON 接口、静态资源服务和前端请求接口的完整闭环。4.6 结果说明与下一步验证此时项目里已经出现了node_modules目录这是 npm 安装依赖后生成的真实文件目录。它会很大不要手动改动它也不要提交到 Git 仓库。在项目中再创建一个.gitignore文件写入以下内容node_modules/这样用 Git 管理项目时依赖目录会被忽略。别人拿到项目后执行npm install就能根据package.json恢复所有依赖。5. 常见问题与排查思路新手在安装和运行 Node.js 项目时会遇到不少环境相关问题。这里整理一份高频问题清单覆盖从安装到运行的大部分典型报错。问题现象常见原因解决思路node不是内部或外部命令Node.js 未安装、环境变量未配置、安装后未重启终端重新安装或手动配置 PATH重新打开命令行窗口nvm install 版本号报 “not yet released or is not available”指定的版本号不存在或尚未发布查看可用版本后重新安装GUI 工具提示 “node.js not found (please save below and restart)”第三方工具配置时无法找到 node 可执行文件检查 node 是否已加入 PATH保存配置文件并重启工具端口报错EADDRINUSE3000 端口已被其他进程占用更换端口或找到并结束占用端口的进程终端中文乱码控制台编码与项目输出编码不一致Windows 可在命令行执行chcp 65001切换到 UTF-8npm install速度很慢默认源连接慢按实际情况配置镜像源安装依赖时出现ERESOLVE依赖冲突依赖版本冲突常见于 npm 高版本升级依赖、检查重复依赖或使用--legacy-peer-depsWindows 7 装不上新版本新版 Node.js 不支持旧系统下载适配旧系统的历史版本浏览器访问localhost:3000无响应服务未启动、端口错误、防火墙拦截查看终端是否输出启动成功日志检查端口更改为其他值node_modules被误删后项目无法启动依赖缺失在项目目录重新执行npm install下面挑几个高频场景展开说明。5.1 安装后提示“node 不是内部或外部命令”这个报错在 Windows 上最常见。安装完成后需要重启命令行窗口让新配置的环境变量生效。如果重启后仍然报错打开系统环境变量设置检查Path变量里是否包含了 Node.js 的安装目录。没有的话手动添加 Node.js 的安装路径例如C:\Program Files\nodejs\。使用 nvm-windows 管理版本时执行nvm use 22.13.1后如果看不到 node 命令先执行nvm list确认版本确实已经安装然后重新打开终端。5.2 nvm 安装指定版本时报错提示版本不存在如果你执行了类似nvm install 24.19.0的命令但 Node.js 官方并没有发布这个版本就会得到 “not yet released or is not available” 的提示。此时可以查看当前可用版本列表再选择具体版本安装nvm list available安装一个明确存在的 LTS 版本即可。版本选择不要追新稳定优先。5.3 第三方工具提示找不到 Node.js有些图形化界面工具比如低代码工具或自动化脚本工具在安装配置时会要求选择 Node.js 路径。如果提示 “node.js not found (please save below and restart)”说明工具没有在默认环境变量中找到 node可以在工具配置界面手动指定 node 可执行文件的路径保存后重启工具。配置前先执行where nodeWindows或which nodeLinux/macOS拿到实际路径再填入。5.4 端口被占用Express 常见的报错是Error: listen EADDRINUSE: address already in use :::3000这表示 3000 端口已经被另一个进程占用。解决办法有两种一是修改代码里的端口号例如改成 3001二是找出占用端口的进程并结束它。Windows 可以使用netstat -ano | findstr :3000Linux/macOS 可以使用lsof -i:3000找到对应进程 ID 后再决定是否结束进程。生产环境中千万不要随意 kill 未知进程先确认进程归属再操作。6. 最佳实践与工程建议从“能跑通”到“稳定好用”中间还有一段路要走。下面这些建议来自实际工程中的常见规范适合尽早养成习惯。6.1 使用版本管理工具管理 Node.js不要在系统里只装一个 Node.js 然后一直升级。项目多了以后不同项目可能依赖不同的 Node 版本升级一个可能会影响另一个。推荐使用 nvm 或 nvm-windows 管理多版本并在项目文档中明确标注当前项目使用的 Node 版本。团队协作时还可以在项目根目录添加.nvmrc文件记录版本号内容可以直接写版本号比如22.13.1这样团队成员执行nvm use时可以自动切换到对应版本减少环境不一致带来的问题。6.2 依赖管理规范要把node_modules当作缓存目录不要手动修改里面任何文件。所有依赖必须通过npm install 包名安装这样会写入package.json保证别人 clone 项目后可以用一条命令恢复。另一点是区分dependencies和devDependencies。只用于开发阶段的工具比如nodemon应该用-D参数安装。生产环境部署时执行npm install --production就不会安装开发依赖减少不必要的文件。6.3 通过环境变量配置参数端口号、数据库地址、密钥等配置不应该写死在代码里。理想做法是通过环境变量注入代码里提供默认值作为兜底const port process.env.PORT || 3000;这样在本地开发时默认使用 3000 端口部署到服务器后可以通过环境变量覆盖。不同环境的差异由配置管理解决而不是反复改代码再重新部署。6.4 异常处理与进程稳定Node.js 的特点是异步回调多未捕获的异常可能导致进程直接崩溃。在开发阶段可以在入口文件监听未处理异常并打印日志process.on(unhandledRejection, (reason, promise) { console.error(Unhandled Rejection at:, promise, reason:, reason); }); process.on(uncaughtException, (err) { console.error(Uncaught Exception:, err); });但要注意这只是让问题暴露得更容易定位不能替代业务层面的错误捕获。接口业务代码应该使用 try-catch 包裹可能出错的逻辑并在响应中返回合理的错误提示。6.5 生产环境部署建议生产环境中不要使用nodemon启动服务它只适合开发调试。更稳妥的方式是使用进程管理工具比如pm2。它可以守护进程应用崩溃时自动重启还可以管理日志输出。生产上线前还需要注意不要用 root 用户直接运行 Web 服务尽量使用独立低权限账号敏感信息比如数据库密码、密钥不要写进代码仓库应通过环境变量或专门的配置服务管理生产环境错误提示不要返回完整堆栈避免信息泄露。6.6 日志与可观测性console.log用于开发调试很方便但在生产环境中信息太零散。推荐使用日志库比如winston、pino按级别输出日志并区分访问日志和错误日志。使用pm2时也可以配置日志文件输出。一个好的日志体系能大幅降低线上问题排查成本。6.7 保持学习路径清晰入门阶段先把一个简单 Web 服务跑通理解请求和响应的基本流程。接下来按顺序学习 Express 中间件机制、RESTful API 设计、连接数据库、用户认证、部署上线逐步形成完整闭环。如果发现某个知识点反复出错先停下来查基础不要急于抄写完功能就结束。7. 总结与学习路线经过这一小时的实践你已经完成了这些关键步骤理解了 Node.js 作为 JavaScript 运行时环境的基本定位安装了 Node.js 和 npm并通过 nvm 学会了版本管理熟悉了 package.json、模块系统、npm 常用命令用原生 http 模块写出了第一个 HTTP 服务使用 Express 搭建了包含页面、JSON 接口和静态资源的 Web 应用最后还掌握了一套常见报错排查方法。下一步可以尝试改造这个项目增加更多 RESTful 接口把接口数据接入 MySQL 或 MongoDB使用模板引擎渲染页面实现简单的登录注册功能最后把应用部署到云服务器上。建议选择一个你感兴趣的小项目比如待办事项管理工具从设计数据结构开始完整走一遍开发流程。只有亲自动手改代码、跑服务、查报错才能把 Node.js 的知识点真正串起来。如果在后续的安装或运行过程中遇到新问题优先检查版本号、终端是否重启、依赖是否完整安装、端口是否被占用这几类常见原因。把报错信息完整复制到搜索引擎中多数问题都能找到对应解法。这篇文章中的示例代码可以直接复制使用也可以在此基础上扩展成属于你自己的第一个 Node.js 应用。