一个内部小工具要加一个查询接口。同事在空目录里执行 npm init -y,装了 Express,写了十行代码,node index.js 也顺利启动。浏览器打开 127.0.0.1:3000/health,屏幕上只有一行 Cannot GET /health。代码里明明写着路由,为什么服务端说找不到?后来发现他写的是 app.get('/api/health'),请求时漏了 /api。Express 不会提示「你可能想访问另一个路径」,它只按注册的规则匹配。

第二个问题更隐蔽。照着一篇 2021 年的教程写 app.get('*', ...) 做兜底路由,升级到 Express 5 后进程直接启动失败,终端里是 PathError [TypeError]: Missing parameter name at index 1: *,最后一行还标着 originalPath: '*'。这不是装错了包,而是 Express 5 换了路径解析库,通配符必须写成有名字的形式,比如 *splat。

第三个问题出在模块体系。同一个项目里,一个文件用 require 引包,另一个用 import,启动时冒出一句 Cannot use import statement outside a module。Express 本身不关心你用哪种模块写法,但 Node 关心,package.json 里少一行 "type": "module",整条链路就跑不起来。这篇从一个真正能跑的空目录开始,把 Express 5 的依赖、目录、启动命令和第一个 JSON 接口串成一条完整链路,再解释什么时候不该选 Express。

先选框架:Express、NestJS 还是 Fastify

框架这个词容易让人期待过高。对 Node.js 的 Web 框架来说,核心工作其实只有三件:把 HTTP 请求解析成对象、按路径和方法分派给处理函数、在分派前后插入可复用的处理步骤。Express 是这三件事最薄的一层封装,它不规定目录,不规定分层,也不规定你怎么校验参数,所以同一家公司能写出十种风格的 Express 项目。

选型时先看团队和业务的形状,而不是先看跑分。下面这张表是本组文章使用的判断口径:

框架核心心智模型适合的场景主要代价
Express 5中间件栈加路由表,几乎所有能力都可通过中间件拼装中小型 API、内部服务、需要快速接手老项目、以 REST 为主没有强制分层,团队要自己定规范;生态里不少中间件仍按 4.x 写法
NestJS 11模块、控制器、服务加依赖注入,约定优于配置多人协作的中大型后端、需要清晰的模块边界、GraphQL 或微服务拆分TypeScript、装饰器和 DI 的学习成本;简单接口也会多出几个文件
Fastify 5路由加钩子,用 JSON Schema 描述输入输出吞吐优先、接口契约稳定、希望用 schema 做校验和序列化生态和人才储备小于 Express;schema 写多了维护成本上升

本组文章主推 Express 5,理由不是它「最好」,而是它把决策权留给你:Node 24 下可以直接用 ESM,异步处理函数的错误在 5.x 里会被自动转交给错误中间件,学习成本低到一个人半天就能跑通一条接口。对于大多数业务 API,真正的瓶颈在数据库查询、外部调用和缓存,不在框架这层函数调用上。

什么时候该选 NestJS?当项目有明确的领域划分、需要依赖注入来替换实现、需要 Guard 统一做鉴权、需要 Interceptor 统一做响应包装,而且团队愿意接受 TypeScript 装饰器带来的编译期成本时,NestJS 的约定能省掉大量「这个文件该放哪」的讨论。它不是 Express 的替代品,默认适配器就跑在 Express 上,两者并不是互斥的世界观。

Fastify 适合把接口契约写得很死的场景。它的 schema 既能校验入参,也能加速序列化,但前提是团队愿意维护 schema,并且真的按 schema 改代码。若只是想要「快」,先确认数据库和外部依赖已经优化过,否则换框架带来的收益很快会被一次全表扫描吃掉。

package.json、ESM 与两条启动命令

从空目录开始,第一步不是写代码,而是把项目的「身份」写清楚:用什么模块体系、跑在什么 Node 版本、启动时执行哪个文件。下面这份 package.json 是本组示例的起点,依赖只有 Express:

{
  "name": "orders-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  },
  "dependencies": {
    "express": "^5.3.0"
  }
}

"type": "module" 这一行决定 .js 文件按 ESM 解析,才能直接写 import express from 'express'。没有它,Node 会把 .js 当成 CommonJS,import 语句在加载阶段就报错。engines.node 是给人和 CI 看的约束,npm 默认只警告不阻断,但部署脚本可以拿它做检查。

安装命令在 Node 24.21.0、npm 11.19.0 下实测通过:

npm install express@5 --no-audit --no-fund

实际输出是 added 65 packages in 7s,装到的 Express 版本为 5.3.0。这里没有用 npm init -y 生成的默认字段,因为默认的 "type": "commonjs" 会让后面的 ESM 代码全部失效,这是新手最常踩的一脚。

启动有两条命令。npm start 跑的是 node src/server.js,适合验证和生产;npm run dev 跑的是 node --watch src/server.js,文件变化后 Node 自己重启进程,不需要装 nodemon。Node 24 的 --watch 已经足够稳定,少一个开发依赖就少一份供应链风险。

真实启动日志是一行 JSON,方便后面接日志系统:

{"msg":"listening","port":3000,"pid":13344}

这行日志是代码里主动打印的,不是框架行为。把「监听成功」写成结构化 JSON,后续收集到日志平台时可以直接按字段过滤,比一句中文「服务已启动」有用得多。

为什么把 app.js 和 server.js 拆开

很多入门示例把 app.listen() 和路由写在一个文件里,跑起来没问题,但测试和优雅退出会变麻烦。本组统一拆成三层,每层只负责一件事:

app.js: 组装 Express 实例:挂中间件、注册路由、注册 404 和错误处理。它不监听端口,因此可以在测试里直接拿去发请求。
server.js: 读取配置、调用 createApp()、监听端口、注册退出信号。它负责进程生命周期,不关心业务路由。
配置与环境: 端口、数据库地址、密钥从环境变量进入,代码里不写死。启动时校验一次,缺什么就明确报错。

拆开之后,createApp() 返回一个尚未监听的实例。写集成测试时不用先抢端口,直接用它发请求即可;同一套路由也能在脚本里创建多个实例。等到第 6 篇讲优雅退出时,server.js 会是唯一需要改动的文件,路由层完全不受影响。

下面是 src/app.js 的完整内容。它包含一个健康检查、一个带参数校验的查询接口、一个故意抛错的接口,以及 404 和统一错误处理:

import express from 'express';

export function createApp() {
  const app = express();
  app.disable('x-powered-by');
  app.use(express.json());

  app.get('/health', (req, res) => {
    res.json({
      status: 'ok',
      service: 'orders-api',
      uptime: Math.round(process.uptime()),
    });
  });

  app.get('/api/orders/:id', (req, res, next) => {
    if (!/^\d+$/.test(req.params.id)) {
      const err = new Error('订单号必须是数字');
      err.status = 400;
      return next(err);
    }
    res.json({ id: Number(req.params.id), status: 'paid', amount: 128.5 });
  });

  app.get('/boom', () => {
    throw new Error('演示:处理函数抛错');
  });

  app.use((req, res) => {
    res.status(404).json({ error: 'not_found', path: req.path });
  });

  app.use((err, req, res, next) => {
    const status = err.status || 500;
    res.status(status).json({
      error: status === 500 ? 'internal_error' : 'bad_request',
      message: err.message,
    });
  });

  return app;
}

app.disable('x-powered-by') 去掉响应头里的 X-Powered-By: Express。它不是安全措施,只是减少一点无用的指纹。真正需要隐藏技术栈时,靠的是不泄露堆栈和内部错误信息,而不是删一个响应头。

src/server.js 只做四件事:读端口、建实例、监听、接信号。第 6 篇会把它扩展成完整的排空逻辑,这里先保留最小版本:

import { createApp } from './app.js';

const port = Number(process.env.PORT || 3000);
const app = createApp();
const server = app.listen(port, () => {
  console.log(JSON.stringify({ msg: 'listening', port, pid: process.pid }));
});

for (const sig of ['SIGINT', 'SIGTERM']) {
  process.on(sig, () => {
    server.close(() => process.exit(0));
  });
}

注意 import './app.js' 里的扩展名。ESM 不做扩展名猜测,漏掉 .js 会在启动时报 ERR_MODULE_NOT_FOUND。这一点和 CommonJS 不同,也是从老项目迁移时最容易批量出问题的地方。

完整链路:从空目录到 /health

把上面的文件放好,目录结构如下。这里用缩进表示层级,不用任何制表符画线:

orders-api/
  package.json
  src/
    app.js
    server.js

完整操作顺序是:创建目录,写 package.json,执行 npm install express@5,写两个源文件,执行 npm start,最后用 curl 发请求。每一步都能独立验证,出问题时容易定位。

健康检查的真实请求与返回:

curl -i 127.0.0.1:3000/health

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 50

{"status":"ok","service":"orders-api","uptime":16}

一次请求在 Express 内部的路径可以画成这样:

一个请求穿过 Express 的最小链路
TCP 收到请求
express.json 解析体
按方法和路径匹配路由
处理函数写响应
未匹配则落到 404

匹配不到路由时,返回的是我们自己注册的 JSON,而不是 Express 默认的 HTML:

curl -i 127.0.0.1:3000/nope

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":"not_found","path":"/nope"}

注意 404 中间件必须放在所有路由之后。Express 按注册顺序从上到下匹配,如果它写在 /health 之前,健康检查的请求会先被它截住,同样返回 404。这不是框架的问题,而是注册顺序的问题。同理,四参数的错误中间件必须放在最后,否则它前面的路由抛错时根本走不到它。

参数不合法时,处理函数把错误交给 next(err),最终由错误中间件统一成 400:

curl -i 127.0.0.1:3000/api/orders/abc

HTTP/1.1 400 Bad Request

{"error":"bad_request","message":"订单号必须是数字"}

处理函数里同步抛错时,Express 5 会捕获并转交错误中间件,返回 500:

curl -i 127.0.0.1:3000/boom

HTTP/1.1 500 Internal Server Error

{"error":"internal_error","message":"演示:处理函数抛错"}
错误中间件把 err.message 原样返回给客户端,只适合演示。生产环境应返回稳定的错误码,把堆栈和内部信息写进日志,而不是响应体。否则一次数据库报错就可能把表名、SQL 片段甚至连接串泄露出去。

还有一个常见现象:请求里带了 Content-Type: application/json,但请求体不是合法 JSON,express.json() 会直接抛出解析错误。即使路由里根本没读 req.body,这个错误也会发生在中间件阶段,最终返回 400:

curl -i -X POST 127.0.0.1:3000/api/orders -H "Content-Type: application/json" -d "{bad json"

HTTP/1.1 400 Bad Request

{"error":"bad_request","message":"Expected property name or '}' in JSON at position 1 (line 1 column 2)"}

这条返回说明一件事:请求体解析是全局中间件的工作,不是路由的工作。只要挂了 express.json(),所有带 JSON 体的请求都会先过这一关。第 2 篇会详细拆中间件顺序。

配置:用 node --env-file,不必先装 dotenv

端口和数据库地址不应该写死在代码里。Node 24 自带 --env-file,启动时读取一个文件并注入环境变量,不需要额外依赖:

node --env-file=.env src/server.js

文件不存在时,Node 直接报错并退出,退出码为 9,提示是 .env.missing: not found。这在 CI 里是好事,缺配置就应该在启动阶段失败,而不是等到第一个请求才报错。如果希望本地没有 .env 也能跑,用 --env-file-if-exists,它会打印 .env.missing not found. Continuing without it. 然后继续。

下面这个文件只放本地开发值,绝不能提交到仓库:

PORT=3210
DATABASE_URL=postgres://app:secret@127.0.0.1:5432/orders
JWT_SECRET=dev-only-not-for-production

与之配套提交的是 .env.example,只保留键名和说明,不保留真实值。团队新人复制一份改名即可,CI 用平台注入的变量覆盖。

读取端口时要显式转换并校验。process.env.PORT 永远是字符串,空字符串也会被 Number() 转成 0,导致服务监听在一个随机端口上:

const raw = process.env.PORT;
const port = Number(raw);
if (!raw || !Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error(`PORT 配置不合法: ${raw}`);
}

这类校验在项目变大后应该集中到一处,用 zod 之类的库一次校验全部变量。第 6 篇会给一份完整的启动校验。现在只要记住原则:配置错了就启动失败,不要用默认值悄悄兜住。

--env-file 读取的变量不会覆盖已经存在的环境变量。容器里平台注入的 PORT 优先级更高,这个行为正好符合十二要素应用的约定。

Express 与 NestJS 的一次对照

Express 项目跑起来之后,最常见的疑问是「要不要换 NestJS」。先看两者在同一件事上的写法差异,不涉及完整教程。

Express 5 的做法

路由和处理函数放在一起,依赖通过参数或模块导入。分层靠目录约定,校验、鉴权、日志都写成中间件,按注册顺序执行。启动入口是普通脚本,调试时看调用栈就是最终调用栈。

NestJS 11 的做法

控制器只声明路由,业务放在可注入的 Service,模块负责装配。Guard 做鉴权、Pipe 做校验、Interceptor 做统一包装,执行顺序由框架规定。启动入口是 NestFactory.create(),调试时多了一层 DI 容器。

判断点不在代码行数,而在约束来源。Express 的约束来自团队自觉:命名、目录、错误码、校验方式都要自己定,人员流动时容易走样。NestJS 的约束来自框架:新成员即使不认同,也得按模块和装饰器写,长期看更整齐,但简单需求也要付出模板成本。

一个务实的迁移信号是:项目里开始出现多个领域、每个领域都有自己的鉴权和校验规则,而 Express 中间件栈已经排到十几层,顺序改一次就要回归全站。这时把边界清楚的模块迁到 NestJS,收益比继续在 Express 里造「小框架」更大。反过来,只有三五个接口的内部工具,用 NestJS 往往是在给未来的维护者增加阅读成本。

现象、真实原因与第一步

起步阶段的问题大多不是「Express 坏了」,而是路径、模块体系或端口对不上。下面这张表按实际排查顺序排列:

现象真实原因第一步查什么
返回 Cannot GET /health请求路径与注册路径不一致,或路由注册在 404 之后打印所有已注册路由,核对前缀、尾斜杠和方法
启动即报 Missing parameter name at index 1: *Express 5 的通配符必须命名,旧写法 * 不再合法改成 /*splat 或 /{*splat},或直接用 app.use 做兜底
启动报 EADDRINUSE端口已被另一个进程占用,常见于上次的 --watch 没退干净用 netstat -ano 找 PID,结束旧进程或换 PORT
Cannot use import statement outside a modulepackage.json 缺少 "type": "module",或文件后缀是 .cjs检查 type 字段与文件后缀,ESM 导入要带 .js
req.body 是 undefined没挂 express.json(),或请求没带 JSON 的 Content-Type确认中间件在路由之前注册,检查请求头
node --env-file=.env 直接退出文件不存在、路径不对,或用了相对路径但工作目录不同用绝对路径或 --env-file-if-exists,打印当前工作目录
进程启动后立刻退出,没有明显报错listen 的错误没有被处理,异步阶段抛错后进程结束给 server.on('error') 加日志,确认 listen 确实执行
接口返回 HTML 而不是 JSON命中了 Express 默认 404,或错误发生在自定义中间件之前看响应 Content-Type,补上自己的 404 兜底

边界与代价

Express 最大的代价是「什么都要自己定」。目录怎么分、错误体什么形状、参数在哪校验、鉴权中间件放在哪、日志字段叫什么,框架都不管。三个人三个写法,三个月后新人接手,第一件事是猜。规范不是文档里写一段话就有效,最好落成可执行的约束:统一响应函数、统一错误类、统一校验入口,再加一条 lint 规则拦住在路由里直接拼 SQL。

第二个代价是生态兼容。Express 5 换了路径解析和部分内部实现,一些按 4.x 写的中间件在 5.x 下行为不同,尤其是依赖 req.param、旧通配符或自己解析 URL 的包。引入任何中间件前,先看它的最近发布时间和支持的 Express 版本,不要因为 README 里一句「兼容 Express」就默认能跑。

第三个代价是性能上限。Express 的函数调用和中间件遍历在极高 QPS 下确实有开销,但对绝大多数业务接口,这部分开销远小于一次没有索引的查询。把框架换掉不会自动让慢接口变快,先看数据库和执行计划。反过来,如果业务里有大量 CPU 计算,无论 Express 还是 NestJS 都不该放在请求线程里做,应该交给队列或独立进程。

最后是团队成本。Express 的自由度适合小而稳定的团队;当人数上来、领域变多,框架提供的约束就变成收益。选型不是一次站队,而是判断「我们现在的规模,需不需要别人替我们定规矩」。

当天能自己验证的练习

  1. 新建空目录,按本文的 package.json 执行 npm install express@5,启动后 curl -i 127.0.0.1:3000/health,确认状态码和 JSON 体;再把路由改成 /api/health,用原路径请求,观察 Cannot GET /health。
  2. 临时加一行 app.get('*', (req, res) => res.send('fallback')),启动进程,记下完整的 PathError;改成 app.get('/*splat', ...) 后重启,确认能启动。
  3. 用同一个端口启动第二个实例,观察 listen EADDRINUSE: address already in use :::3000,再用 $env:PORT=3001 启动,确认两个实例可以同时存在。
  4. 执行 node --env-file-if-exists=.env.missing -e "console.log(process.env.PORT || '未设置')",观察提示语和输出,理解「可选配置」和「必需配置」的区别。
  5. 用 curl -X POST ... -d "{bad json" 发一个非法 JSON,记录 400 响应;再注释掉 app.use(express.json()) 重启,确认同一个请求不再报解析错误,但 req.body 是 undefined。

小结

三句话收束:Express 5 的价值是薄和自由,自由需要用规范补上;package.json 的 type、engines 和 scripts 决定了项目能不能稳定启动;app.js 只组装,server.js 管生命周期,这个拆分为测试和优雅退出留出了位置。

下一篇讲路由和中间件。现在只有一个 /health,一旦接口变成十几个,就会遇到「中间件到底按什么顺序执行」「异步错误为什么没进错误处理」「404 兜底为什么把正常路由也吃了」这些问题。下一篇会把一次请求穿过中间件栈的每一步拆开,并用真实响应说明 401、404、500 分别该在哪一层产生。