Express v5 + Socket.IO v4 服务端 + React v19 + Vite v6 前端全栈项目。前后端分离部署,通过 HTTP REST API 和 WebSocket 双向通信。
| 技术 | 版本 | 用途 |
|---|---|---|
| Node.js | ≥18 | 运行时 |
| TypeScript | ^5.7 | 类型安全(strict 模式) |
| Express | ^5.2 | HTTP 框架,提供 REST API |
| Socket.IO | ^4.8 | WebSocket 实时双向通信 |
| tsx | ^4.19 | 开发热重载(watch 模式) |
| 技术 | 版本 | 用途 |
|---|---|---|
| React | ^19.1 | UI 框架 |
| TypeScript | ~5.7 | 类型安全 |
| Vite | ^6.3 | 构建工具 + 开发服务器 |
| socket.io-client | ^4.8 | WebSocket 客户端 |
cost_usage/
├── package.json # 后端根配置
├── tsconfig.json # 后端 TS 配置
├── .gitignore
├── README.md
├── src/ # 后端源码
│ ├── server.ts # 入口:创建 http.Server + listen
│ ├── app.ts # Express 应用组装(不调用 listen)
│ ├── config/
│ │ └── index.ts # 集中配置(端口、CORS)
│ ├── routes/
│ │ ├── index.ts # 路由汇总
│ │ └── health.ts # GET /api/health 健康检查
│ ├── socket/
│ │ └── index.ts # Socket.IO 初始化 + 事件注册
│ └── types/
│ └── socket.ts # Socket.IO 四接口类型定义
└── client/ # 前端(独立模块)
├── package.json # 前端独立依赖
├── tsconfig.json # 前端 TS 配置(ESM + JSX)
├── vite.config.ts # Vite 配置 + 代理规则
├── index.html # Vite 入口 HTML
└── src/
├── main.tsx # React 入口
├── App.tsx # 根组件
├── App.css
├── index.css
└── vite-env.d.ts # Vite 类型声明
┌──────────────────────────────────────────────────────┐
│ 开发环境 │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ 浏览器 │ :5173 │ Vite Dev │ │
│ │ ├───────►│ Server │ │
│ │ │ │ (React HMR) │ │
│ └──────────┘ └───┬────┬─────┘ │
│ ▲ │ │ │
│ │ 静态资源 │ │ /api/* │
│ │ (React 页面) │ │ /socket.io/* │
│ │ │ │ (proxy 转发) │
│ └──────────────────┘ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ http.Server │ :3000 │
│ │ (Express + │ │
│ │ Socket.IO) │ │
│ └──────────────┘ │
└──────────────────────────────────────────────────────┘
核心设计:
- 后端
app.ts只负责组装 Express(中间件 + 路由),绝不调用listen() server.ts创建共享的http.Server,把 Express 和 Socket.IO 都挂上去,统一listen()- 前端
client/是独立的 npm 项目,有自己的package.json、tsconfig.json和构建链 - 开发时 Vite dev server(
:5173)通过 proxy 把/api和/socket.io请求转发到后端(:3000),前端代码直接用相对路径,零 CORS 配置 - 前后端通过 HTTP REST API + WebSocket 通信,天然解耦
# 后端
npm install
# 前端
cd client && npm install需要两个终端分别启动后端和前端:
# 终端 1:启动后端(端口 3000,tsx watch 热重载)
npm run dev
# 终端 2:启动前端(端口 5173,Vite HMR 热更新)
cd client && npm run dev浏览器访问 **http://localhost:5173**,页面会自动:
- 通过 REST 调用
/api/health检查后端健康状态 - 通过 WebSocket 发送
ping,接收pong回执
# 后端编译
npm run build # tsc → dist/
npm start # node dist/server.js
# 前端编译(输出到 client/dist/)
cd client && npm run build生产部署时,可将 client/dist/ 中的静态文件交由 Express 托管,或部署到 CDN。
GET /api/health
响应:
{ "status": "ok", "timestamp": "2026-08-11T02:04:40.095Z" }| 事件 | 载荷 | 说明 |
|---|---|---|
ping |
无 | 服务端通过 ACK 回调返回 "pong" |
// 客户端示例
socket.emit('ping', (response) => {
console.log(response); // "pong"
});| 事件 | 说明 |
|---|---|
pong |
预留主动推送 |
notification |
预留通知事件 |
- 在
src/routes/下创建新文件(如user.ts):
import { Router } from 'express';
const router = Router();
router.get('/users', async (req, res) => {
res.json([{ id: 1, name: 'Alice' }]);
});
export default router;- 在 src/routes/index.ts 中挂载:
import userRouter from './user';
router.use(userRouter);在 src/socket/index.ts 的 io.on('connection', ...) 回调中添加处理逻辑,同时更新 src/types/socket.ts 的 ClientToServerEvents / ServerToClientEvents 接口。
在 client/src/ 下创建新组件,如 client/src/pages/Dashboard.tsx,然后在 App.tsx 中引入路由或直接渲染。
注意: 前端请求后端 API 时使用相对路径(如 fetch('/api/health')),开发时 Vite proxy 自动转发到后端,生产时需根据部署方式调整。
| v4 写法 | v5 写法 |
|---|---|
/* 通配符 |
/{*splat},req.params.splat 是数组 |
res.json(obj, status) |
res.status(status).json(obj) |
res.redirect(url, status) |
res.redirect(status, url)(参数顺序互换) |
异步 handler 需 .catch(next) |
原生支持,自动转发 rejected promise |
req.query 可赋值 |
是 getter,不可赋值 |
express.urlencoded() 默认 extended: true |
默认 extended: false,需显式传入 |
| 位置 | 命令 | 说明 |
|---|---|---|
| 根目录 | npm run dev |
后端开发(热重载,:3000) |
| 根目录 | npm run build |
后端编译(tsc → dist/) |
| 根目录 | npm start |
后端生产启动 |
client/ |
npm run dev |
前端开发(HMR,:5173) |
client/ |
npm run build |
前端构建(→ client/dist/) |
client/ |
npm run preview |
预览前端构建产物 |