从零搭建第一个 Express.js 应用：环境配置与 Hello World 教程

作者：接口漫谈时间：2026-10-30 19:13:00浏览：257

本教程针对初学者，提供从零开始搭建第一个 Express.js 应用的完整指南。涵盖 Node.js 运行环境验证、npm 初始化项目、安装 Express、编写 app.js 核心代码、启动服务与测试验证，并提供代码逐行解析与常见报错排查方案。

分类：Node.js 后端开发难度：入门实操核心栈：Express 4.x / 5.x、Node.js LTS

Express.js 是运行在 Node.js 之上极具代表性的极简 Web 框架。搭建一个最小可运行的 Express 应用，本质上只需要完成三个环节：确认本地 Node.js 运行环境、初始化项目并安装 Express 依赖、编写一个监听指定端口并响应 HTTP GET 请求的脚本文件。本文将按照工业级规范的开发流，从零讲解环境检查、目录初始化、核心代码编写到最终的本地访问验证，并拆解每行代码的实际职能与常见故障排查方案。

从零搭建第一个 Express.js 应用：环境配置与 Hello World 教程 — 图 0：Express.js 体系结构等距分层示意（Node.js 运行时、框架核心与业务应用）

一、前置准备与 Node.js 运行环境检查

Express 并不是一个独立的编译型程序，它是一个发布在 npm 官方仓库中的 Node.js 第三方模块。因此，在开始写代码前，必须确保操作系统中已经正确安装了 Node.js 运行时环境以及 npm（Node Package Manager）包管理工具。

1. 验证本地环境命令

打开系统的终端（macOS / Linux 的 Terminal，或 Windows 的 PowerShell / 命令提示符），分别执行以下两行命令：

node -v
npm -v

终端示例输出

v20.18.0 10.8.2

如果终端输出了形如 v18.x.x 或 v20.x.x 的版本编号，说明 Node.js 环境已经就绪，可以正常进行后续步骤。建议选择官方长期支持版（LTS，Long Term Support），以确保模块依赖的稳定性与向后兼容性。

未安装处理方法：如果系统提示 command not found: node 或“不是内部或外部命令”，请前往 Node.js 官方网站（nodejs.org）下载对应的 LTS 安装包，按照默认向导完成安装并重新打开终端。

二、项目工程初始化与依赖安装步骤

为了保证工程的干净与可移植性，任何 Node.js 项目都应拥有独立的文件夹，并通过 package.json 声明其依赖项。

步骤 1：创建并进入项目工作目录

在合适的文件系统路径下新建项目目录，并将其设为当前终端的工作路径：

mkdir my-express-app
cd my-express-app

步骤 2：初始化 Node.js 项目清单（package.json）

执行 npm init -y 命令。添加 -y（即 yes）参数可以直接使用系统默认选项生成配置文件，避免逐项手动交互：

npm init -y

生成的 package.json 内容示例

{ "name": "my-express-app", "version": "1.0.0", "description": "", "main": "app.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" }

此时目录中会生成 package.json 文件。它是 Node.js 项目的核心元数据文件，记录了工程名称、入口文件定位（如 main 字段）以及接下来要引入的第三方依赖包信息。

步骤 3：安装 Express 核心依赖库

在当前目录下运行以下命令安装 Express：

npm install express

该命令会执行以下关键动作：

从 npm 远程源下载 Express 及其所有底层依赖模块，解压保存在本地新建的 node_modules 文件夹中。
自动将 Express 写入 package.json 的 dependencies 字段中。
自动生成 package-lock.json 文件，精确锁定安装的每一个子模块的具体版本和哈希完整性校验码，确保团队其他成员在不同机器上执行安装时依赖版本完全一致。

三、编写第一个 Hello World 应用

依赖安装完毕后，便可以在项目根目录下创建入口主程序文件。在这里，我们创建名为 app.js 的文件。

1. 完整代码实现

使用代码编辑器（如 VS Code）或终端文本工具创建 app.js，并填入以下 11 行标准实现：

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Express 应用已启动，正在监听 http://localhost:${port}`);
});

2. 代码逐行深入拆解

虽然代码量很短，但每一行都对应着 Node.js 与 Express 运行时的关键机制：

const express = require('express');
采用 CommonJS 规范从 node_modules 目录加载 Express 模块。引入的 express 本质是一个导出函数对象（Exported Factory Function）。
const app = express();
调用该工厂函数，实例化一个 Express 主应用对象 app。这个对象承载了后续的所有路由注册、中间件挂载及网络服务器配置。
const port = 3000;
定义一个端口常量。在 TCP/IP 协议栈中，一个端口在同一时刻只能被一个运行中的进程独占监听。3000 是 Node.js 社区常用的本地开发端口。
app.get('/', (req, res) => { ... });
向应用注册一个路由规则：
- 第一个参数 '/' 是 URL 路径（Pathname），代表网站的根目录。
- 请求方法限定为 HTTP GET。当浏览器访问网址时，默认发送的正是 GET 请求。
- 第二个参数是一个回调函数（Request Handler）。当匹配到符合条件的请求时，Express 会将封装后的请求对象（req）和响应对象（res）注入该回调。
res.send('Hello World!');
res.send() 是 Express 对原生 Node.js HTTP 响应的高级封装。它会自动执行三项繁琐底层工作：
1. 根据传入的内容类型自动设置 HTTP 头 Content-Type: text/html; charset=utf-8。
2. 根据字符串字节长度自动计算并附加 Content-Length 头。
3. 发送 HTTP 状态码 200 OK 并关闭当前连接（内部调用了原生的 res.end()）。
app.listen(port, callback);
底层封装了 Node.js 原生的 http.createServer(app).listen(...) 方法。操作系统内核会为此分配端口并建立监听套接字（Socket）。服务启动成功后会执行回调函数，在控制台打印提示。

四、运行服务与请求验证

编写好 app.js 后，即可在终端启动这个 Web 服务，并通过多种方式验证其是否能够正确响应 HTTP 请求。

1. 启动服务

在 my-express-app 项目根目录下，运行以下命令：

node app.js

控制台输出示例

Express 应用已启动，正在监听 http://localhost:3000

注意：该命令运行后，终端光标会保持挂起状态，不会返回新的命令输入提示符。这表明 Node.js 进程正在持续占用前台，处于事件循环监听中。切勿关闭该终端窗口。

2. 验证方法一：使用网页浏览器访问

打开电脑上的任意主流浏览器（Chrome、Edge、Safari 等），在地址栏输入：

http://localhost:3000

回车后，页面主体区域将清晰显示纯文本 Hello World!，说明服务与网络通信链路完全畅通。

3. 验证方法二：使用终端 cURL 命令行工具

保留服务运行的终端窗口不变，新开一个终端窗口，执行如下 cURL 命令查看完整的 HTTP 协议往返报文：

curl -i http://localhost:3000

cURL 详细输出示例

HTTP/1.1 200 OK X-Powered-By: Express Content-Type: text/html; charset=utf-8 Content-Length: 12 ETag: W/"c-7QdihQuMmIPCGVD3zNjbIgOiFMg" Date: Fri, 30 Oct 2026 02:46:21 GMT Connection: keep-alive Keep-Alive: timeout=5 Hello World!

从输出中可以看出，Express 不仅返回了预期的正文 Hello World!，还规范地附加了 200 OK、X-Powered-By: Express、以及精确计算的 Content-Length: 12。

五、初学者常见问题与排错指南

在实际搭建过程中，初学者常因操作顺序、路径差异或端口冲突遇到报错。以下列出最常见的三种情况与明确的解决办法：

1. 报错：Cannot find module 'express'

错误现象：运行 node app.js 时，控制台抛出未捕获异常：

Error: Cannot find module 'express'
Require stack:
- /path/to/my-express-app/app.js

根本原因：Node.js 的模块寻路机制在当前执行目录及其各级父级目录中均未找到 node_modules/express。通常是因为忘记执行 npm install express，或者在错误的文件夹路径下执行了运行命令。

解决办法：在终端使用 pwd（Windows 为 cd）确认当前路径确实是 my-express-app，然后确认该目录下是否存在 package.json 与 node_modules。若缺失，重新执行 npm install express 即可。

2. 报错：listen EADDRINUSE: address already in use :::3000

错误现象：启动服务时抛出地址已被占用异常：

Error: listen EADDRINUSE: address already in use :::3000

根本原因：操作系统的 3000 端口已被其他服务或之前未正常退出的 Node.js 进程占用。

解决办法：

快速方案（更换端口）：直接修改 app.js 中的 port 变量为 3001 或 8080 并重新启动。
彻底方案（释放端口）：在终端查找占用 3000 端口的进程 PID 并终止。例如 macOS / Linux 下执行 lsof -i :3000 查看 PID 后使用 kill -9 <PID> 杀掉残留进程。

3. 现象：修改 app.js 之后刷新浏览器无变化

根本原因：与 PHP 或静态 HTML 不同，Node.js 采用的是常驻内存机制。服务启动时会将脚本代码一次性加载入内存，后续的代码文件修改不会触发自动热重载。

解决办法：在运行服务的终端界面按下快捷键 Ctrl + C 终止当前进程，然后再次执行 node app.js 重新启动。在开发中，也可以使用 Node.js 18+ 原生支持的 node --watch app.js 模式实现文件修改自动重启。

六、总结与下一步扩展

完成本文的全部操作后，你已经成功建立了标准的 Node.js 工程骨架，安装了 Express 第三方模块，并运行了具备完整 HTTP 协议特性的最小服务。这是掌握现代后端服务开发的基石。

在此基础之上，你可以继续向以下方向进行功能扩展：

增加更多 HTTP 路由：注册更多路径，如 app.get('/api/users', (req, res) => { ... }) 返回 JSON 数据。
支持其他 HTTP 方法：使用 app.post()、app.put()、app.delete() 搭建标准的 RESTful API 接口。
静态资源托管：使用内置的 express.static('public') 快速对外托管 HTML、CSS、图片等前端静态资源。
中间件流水线：引入 express.json() 解析客户端发送的 JSON 请求体数据。