React / 系统课时
启动 Express 应用
启动 Express 应用
本课实现一个可直接启动的 Express TypeScript 服务,统一配置端口、JSON 请求体解析、跨域访问和健康检查。完成后,前端可以通过 HTTP 请求验证后端是否正常工作。
学习目标
- 创建并启动 Express 应用实例
- 理解中间件、路由与响应的执行顺序
- 使用请求验证 JSON 解析、跨域和健康检查
准备项目与依赖
下面命令可在空目录中完成最小初始化;已有 TypeScript 项目时,只需安装 Express、CORS 及对应类型声明。
mkdir express-api
cd express-api
npm init -y
npm install express cors
npm install -D typescript tsx @types/node @types/express @types/cors
npm pkg set type=module
npm pkg set "scripts.dev=tsx watch src/index.ts"
npm pkg set "scripts.build=tsc -p tsconfig.json"
npm pkg set "scripts.start=node dist/index.js"
mkdir src预期结果
项目中生成 package.json、package-lock.json、node_modules 和 src 目录,安装过程无报错。在根目录创建 tsconfig.json,保证 ESM 导入、严格类型检查和 dist 输出目录正常工作。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src/**/*.ts"]
}配置完成后可用 npm run build 验证;没有类型错误时,编译器会生成 dist/index.js。
理解请求处理链路
浏览器请求进入 Express 后,会按注册顺序依次经过跨域中间件、JSON 解析中间件和目标路由。顺序错误时,可能出现跨域失败或 req.body 为空。

实现 Express 服务
创建 src/index.ts。跨域配置只允许本地 React 开发地址;express.json 将 JSON 请求体解析为对象,并限制最大体积,避免无边界读取。
import cors from "cors";
import express, { type Request, type Response } from "express";
const app = express();
const port = Number(process.env.PORT ?? 3000);
app.use(
cors({
origin: "http://localhost:5173",
}),
);
// 必须在需要读取 req.body 的路由之前注册
app.use(express.json({ limit: "1mb" }));
app.get("/health", (_req: Request, res: Response) => {
res.status(200).json({ status: "ok" });
});
app.post("/api/echo", (req: Request, res: Response) => {
res.status(200).json({ received: req.body });
});
app.listen(port, "0.0.0.0", () => {
console.log(`API listening on http://localhost:${port}`);
});启动开发服务器。
npm run dev预期输出
API listening on http://localhost:3000若设置了 PORT 环境变量,实际端口会替换为对应的 <PORT>。
验证健康检查与 JSON 解析
先请求健康检查接口。它不依赖数据库,适合部署平台判断进程是否可以接收请求。
curl -i http://localhost:3000/health预期输出
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"ok"}再携带允许的前端来源和 JSON 请求体调用回显接口,同时验证 CORS 响应头与 express.json。
curl -i -X POST http://localhost:3000/api/echo \
-H "Origin: http://localhost:5173" \
-H "Content-Type: application/json" \
-d '{"message":"hello"}'预期输出
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://localhost:5173
Content-Type: application/json; charset=utf-8
{"received":{"message":"hello"}}响应头顺序和其他默认头可能不同,但状态码、允许来源和 JSON 响应体应保持一致。
处理常见启动问题
出现 EADDRINUSE 表示端口已被占用,可停止旧进程或改用其他 PORT。浏览器仍提示跨域时,应检查实际前端来源是否与 origin 完全一致,包括协议和端口。
若 /api/echo 返回的 received 为空,先确认请求头是 Content-Type: application/json,再检查 app.use(express.json()) 是否注册在路由之前。生产环境不要长期使用任意来源跨域,应从环境变量读取允许列表。