Node.js 安装配置与第一个 HTTP 服务器编写

作者：星河

时间：2026-11-05

本文系统讲解 Node.js 的安装与环境变量配置流程，提供跨平台安装建议与验证方法，并基于原生 http 模块深入实现第一个 HTTP 服务器，解析请求响应生命周期及排查常见运行问题。

文章目录

服务端开发基础教程

适用环境：Windows / macOS / Linux • Node.js LTS 版本 • 原生标准模块零依赖

Node.js 是一款基于 Chrome V8 引擎构建的 JavaScript 服务端运行环境，它打破了 JavaScript 仅能在浏览器端运行的限制，赋予其直接调用操作系统底层网络与文件系统的能力。本文围绕 Node.js 的标准安装配置以及原生 HTTP 服务器的编写展开：首先梳理跨平台环境安装与环境变量生效的核查要点，随后使用内置的 node:http 模块编写第一个常驻网络服务并剖析请求响应生命周期，最后梳理端口冲突、编码乱码等常见异常的排查方法。

Node.js 安装配置与第一个 HTTP 服务器编写 — 图 1：Node.js 运行时与 HTTP 架构全貌（客户端请求、事件循环分发与业务逻辑层）

一、版本选型与跨平台安装步骤

搭建 Node.js 开发环境的核心在于版本选择与安装包获取。在进入具体安装前，需要明确官方发布的两种版本类型：

LTS（Long Term Support，长期支持版）：版本代号为偶数（如 v18、v20、v22 等）。官方提供长达 30 个月的安全更新与缺陷修复，API 保持高度稳定，第三方包兼容性最好。无论是用于生产环境部署还是日常技术学习，都应当将 LTS 作为默认选择。
Current（最新特性版）：版本代号通常为奇数或最新大版本。包含 ECMAScript 新语法试验、前沿内置 API 以及性能改动，但存在后续 API 调整的风险，不适合初学者构建基础服务。

1. 官方安装包安装（适合个人开发机常规安装）

访问 Node.js 官方网站（nodejs.org），网站通常会根据访问设备自动识别操作系统，并优先展示 LTS 版本的下载按钮：

Windows 操作系统：下载 .msi 格式的 Windows Installer 安装包。双击启动安装向导，按照默认路径进行安装。在“Custom Setup”（自定义安装）界面中，务必保持 “Add to PATH” 选项处于启用状态，安装程序会自动将 Node.js 根目录及 npm 目录写入系统环境变量。
macOS 操作系统：下载 .pkg 格式的安装包，双击启动引导，系统会自动将 Node.js 二进制文件安装至 /usr/local/bin（Intel 芯片机型）或 /opt/homebrew/bin，并配置好基础全局软链接。

2. 命令行与多版本管理器安装（推荐场景）

在 Linux 服务器环境，或需要在一台电脑上管理多个不同项目的 Node.js 版本时，直接使用安装包可能导致版本冲突或依赖权限污染。此时推荐使用版本管理工具 nvm（Node Version Manager）：

Bash / Zsh 终端执行指令（示例）

# 1. 安装最新 LTS 版本
nvm install --lts

# 2. 设置当前终端及全局默认使用该 LTS 版本
nvm use --lts
nvm alias default 'lts/*'

# 3. 查看本地已安装的所有版本列表
nvm ls

安装后关键动作提醒

安装完成后，请彻底关闭当前已打开的命令行终端（Command Prompt、PowerShell 或 Terminal），然后重新启动一个新的终端窗口。这是因为新安装程序写入的操作系统的环境变量 PATH，只有在新建的终端进程中才会被完全读取加载。

二、环境配置与可用性验证

完成安装之后，必须在终端执行指令检验运行环境与包管理工具是否已经能够被操作系统正确识别。

1. 检验 Node.js 与 npm 核心指令

在新打开的终端窗口中依次输入以下两条命令：

终端命令及示例输出

$ node -v
v20.18.0

$ npm -v
10.8.2

输出含义说明：node -v 输出了代表 Node.js 核心运行时的版本号，表明 V8 引擎和系统调用层已就绪；npm -v 则输出了随 Node.js 捆绑发布的包管理工具版本号。如果两条命令均能清晰打印出版本数字，表明安装已经成功。

2. PATH 环境变量工作原理解析

当我们在终端中敲击 node 命令时，操作系统并非在全盘进行穷举查找，而是按从前到后的顺序遍历系统环境变量 PATH 中登记的各个目录：

在 Windows 下，系统在 PATH 包含的目录下寻找 node.exe；
在 macOS 或 Linux 下，系统在 PATH 包含的目录下寻找带有可执行权限的 node 二进制文件。

如果终端提示 command not found: node（macOS/Linux）或 'node' 不是内部或外部命令，也不是可运行的程序（Windows），说明系统的 PATH 中缺失了 Node.js 的安装路径。对于 Windows 用户，可打开“系统属性 ➔ 高级 ➔ 环境变量”，在系统变量 Path 中手动追加 Node.js 的安装路径（例如 C:\Program Files odejs\），保存后重新开启终端即可恢复正常。

三、编写第一个 HTTP 服务器

Node.js 的原生标准库中自带了 http 模块（现代写法推荐带命名空间前缀 node:http），它直接基于底层的 TCP 套接字封装了对 HTTP/1.1 协议报文的编解码能力。在初学阶段，直接使用原生模块可以清晰洞察请求与响应的生命周期，无需额外安装任何第三方依赖。

1. 创建工作目录与初始化文件

建议为每个练习项目创建独立的目录，保持工程结构整洁。在终端中执行如下操作：

终端命令

# 创建项目目录并进入
mkdir my-http-server
cd my-http-server

# 可选：初始化 package.json 包描述文件
npm init -y

在该目录下新建名为 server.js 的源码文件，使用任意代码编辑器（如 VS Code、Sublime Text 或 Vim）打开。

2. 编写完整的 server.js 代码

将以下完整代码写入 server.js 文件中：

server.js 源码实现

// 1. 引入 Node.js 内置的原生 http 模块
const http = require('node:http');

// 2. 规划服务监听的主机地址与网络端口
const HOSTNAME = '127.0.0.1'; // 127.0.0.1 代表本地回环地址（localhost）
const PORT = 3000;            // 设定监听端口为 3000

// 3. 使用 createServer 创建 HTTP 服务实例
const server = http.createServer((req, res) => {
  // 打印客户端请求的基础摘要信息到控制台
  const now = new Date().toLocaleTimeString();
  console.log(`[${now}] 收到网络请求: ${req.method} ${req.url}`);

  // 设置 HTTP 响应状态码及响应头
  // 关键：声明 text/plain 并指明 charset=utf-8，确保中文字符在客户端正确解析
  res.writeHead(200, {
    'Content-Type': 'text/plain; charset=utf-8',
    'X-Powered-By': 'Node.js-HTTP-Core'
  });

  // 向响应数据流中写入内容并结束请求
  res.end('你好，这是我的第一个 Node.js HTTP 服务器！\n');
});

// 4. 绑定端口与主机，正式启动监听
server.listen(PORT, HOSTNAME, () => {
  console.log(`[Server] 服务已成功启动！`);
  console.log(`[Server] 本地访问入口: http://${HOSTNAME}:${PORT}/`);
  console.log(`[Server] 控制台提示: 可随时在当前终端按下 Ctrl + C 终止进程。`);
});

3. 核心 API 运行机理深度剖析

上述代码逻辑精简，但涵盖了服务端网络编程的三个核心环节：

http.createServer(callback)：该方法底层构建在 TCP 模块 net.Server 之上。Node.js 会自动监听操作系统底层套接字网络事件。当检测到完整的 HTTP 标头到达后，事件循环会分发一个名为 request 的事件，并触发我们传入的回调函数。
req（http.IncomingMessage 实例）：代表客户端传入的请求对象。它是一个可读流（Readable Stream），挂载了请求的元数据，包括 req.method（GET、POST 等方法）、req.url（请求路径及参数）以及 req.headers（请求头部键值对）。
res（http.ServerResponse 实例）：代表发往客户端的响应对象。它是一个可写流（Writable Stream）。
- res.writeHead(statusCode, headers)：负责将 HTTP 状态码（200 OK）以及首部字段写入网络缓冲区；
- res.end(data)：该方法是必须调用的关键步骤。它将最终的响应主体数据推入底层 TCP 套接字，并向协议层发送结束标记。如果遗漏 res.end()，底层连接将一直挂起，浏览器端会持续处于“正在加载”的阻塞状态直至超时。

四、启动服务与多途径访问测试

完成代码编写后，即可通过命令行宿主启动服务进程，并通过图形化浏览器与命令行工具分别进行协议级检验。

1. 启动服务进程

在工作目录终端中执行以下启动指令：

终端命令及运行状态

$ node server.js
[Server] 服务已成功启动！
[Server] 本地访问入口: http://127.0.0.1:3000/
[Server] 控制台提示: 可随时在当前终端按下 Ctrl + C 终止进程。

为什么终端没有退出？平时运行计算类 JS 脚本时，代码执行完毕就会立即回到命令提示符。而在当前程序中，server.listen() 向 Libuv 事件循环注册了一个长期活跃的网络监听句柄（TCP Handle）。只要该监听未被显式注销，Node.js 进程就会常驻操作系统内存，时刻准备接受外来网络连接。

2. 途径一：Web 浏览器可视化访问

保持终端窗口处于运行状态，打开电脑中的 Chrome、Firefox、Edge 或 Safari 浏览器，在顶部地址栏输入：

http://127.0.0.1:3000

按下回车后，网页正文中央将立即呈现出我们在 res.end() 中填写的文本内容：

浏览器预期呈现结果

你好，这是我的第一个 Node.js HTTP 服务器！

切换回服务运行终端，可以看到控制台已经打印出类似 [14:32:01] 收到网络请求: GET / 的日志输出。部分现代浏览器在访问网页时，还会自动向服务端发起一次 GET /favicon.ico 请求以尝试获取网站图标，因此终端记录两条访问日志属于正常现象。

3. 途径二：终端 cURL 工具进行协议级检验

打开第二个终端窗口，通过 curl 命令行工具配合 -i（包含 HTTP 响应头）参数直接发起网络请求：

终端 cURL 命令及返回的原始 HTTP 报文

$ curl -i http://127.0.0.1:3000
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-Powered-By: Node.js-HTTP-Core
Date: Sat, 31 Oct 2026 06:50:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Content-Length: 64

你好，这是我的第一个 Node.js HTTP 服务器！

通过该报文可以看到完整的 HTTP 通信细节：状态行声明了协议版本与 200 OK 状态；自定义与标准响应头整齐罗列；空行之后紧随响应实体内容。这证明 HTTP 服务器已符合标准网络协议规范。

五、常见故障排查与深度避坑指南

在初次搭建与运行 Node.js 服务端程序时，初学者通常会遭遇几类特定现象。理解这些异常背后的根因可以大幅降低调试阻力。

1. 端口占用异常：Error: listen EADDRINUSE

错误表现：在终端执行 node server.js 时，程序没有打印启动成功日志，而是立即崩溃退出，并输出如下堆栈报错：

终端报错堆栈示例

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000
    at Server.setupListenHandle [as _listen2] (node:net:1904:16)
    at listenInCluster (node:net:1961:12)
    at node:net:2135:7 ...

根本原因：计算机网络中，每个具体的端口在同一时刻仅允许一个进程绑定监听。出现此错误通常意味着：之前启动的 server.js 进程尚未通过 Ctrl + C 关闭仍在后台运行；或者本地安装的其他开发软件（如 Webpack 开发服务器、某些后端中间件）已经占用了 3000 端口。

排查与处置手段：

快捷方式：直接修改 server.js 代码中的端口变量，如修改为 const PORT = 3001;，再次启动即可绕开占用。
彻底解决（macOS / Linux）：在终端运行 lsof -i :3000 查看占用该端口的进程标识符（PID），确认后执行 kill -9 <PID> 强制杀掉旧进程。
彻底解决（Windows）：在命令行运行 netstat -ano | findstr :3000 查找到对应的 PID，随后在任务管理器中结束对应进程，或在命令行执行 taskkill /F /PID <PID>。

2. 浏览器页面中文显示为乱码

错误表现：英文、数字输出正常，但中文内容在浏览器端显示为问号方块或异常字符（如 é»„é‡‘、）。

根本原因：Node.js 底层默认使用 UTF-8 字符编码对字符串进行二进制字节流序列化。然而如果 HTTP 响应头只给出了 Content-Type: text/plain 而没有显式声明字符集，部分浏览器根据本地环境规则可能会默认采用 ISO-8859-1 或 GBK 规则进行文本解码，导致字节还原错位。

处置手段：在 res.writeHead() 中必须严格配置完整的 MIME 类型与字符集：

// 纯文本输出时：
res.setHeader('Content-Type', 'text/plain; charset=utf-8');

// 若输出 HTML 片段时：
res.setHeader('Content-Type', 'text/html; charset=utf-8');

3. 修改代码后刷新页面无任何变化

错误表现：开发者在 server.js 中把返回的字符串修改为新文字并保存，但回到浏览器刷新，展示的依旧是修改前的旧内容。

根本原因：Node.js 与前端网页开发或者 PHP 脚本的即时解释执行机制不同。Node.js 在执行 node server.js 启动的瞬间，就已经将 JavaScript 脚本解析并驻留到 V8 虚拟机的内存中。服务在接收后续网络请求时，直接运行内存中的闭包函数，不会主动去重新读取磁盘上的文件变动。

处置手段：

常规方式：每次修改完代码并保存后，在运行服务的终端界面按下快捷键 Ctrl + C 结束当前进程，随后再次执行 node server.js 重新加载。
现代化内置监听（Node.js v18.11+）：Node.js 官方已内置文件监视能力，启动时追加 --watch 参数即可：
```
node --watch server.js
```
启动后，Node.js 会自动监控项目目录下的文件变更，一旦保存文件便会自动无缝重启服务，无需每次手动反复中断。

六、核心要素汇总与进阶学习导引

为了便于速查回顾，下表系统总结了搭建 Node.js 开发环境与编写基础 HTTP 服务时的关键要素及对照关系：

技术环节	核心指令 / 关键 API	作用说明与判定标准
版本核对	`node -v` / `npm -v`	确认运行时与包管理工具已正确就绪，且在终端 PATH 中生效。
模块引入	`require('node:http')`	载入原生 HTTP 协议处理组件，零外部安装包依赖。
实例构建	`http.createServer(callback)`	实例化服务器，挂载以 `(req, res)` 为参数的双向处理回调。
响应控制	`res.writeHead()` & `res.end()`	规范设置 HTTP 状态码与 UTF-8 字符集，提交数据并切断数据流。
服务驻留	`server.listen(PORT, HOST)`	向操作系统绑定套接字端口，使事件循环进入持续监听状态。
开发调试	`node --watch server.js`	启用原生监听机制，在代码发生改动时自动热重启进程。

掌握了原生 http 模块的使用之后，你就已经理解了 Web 服务底层最本质的“请求-响应”通信模型。后续若需要实现多页面访问，可通过 req.url 进行条件分支判断来设计基础路由系统；若需要返回静态页面或图片，可结合原生 node:fs 文件系统模块将本地文件读取为流输出给客户端；而在面对复杂的大型业务系统时，再进一步引入 Express、Koa 或 Fastify 等高级封装框架，就能更加自如地应对中间件组合与架构扩展。