在线视频聊天项目说明

项目概述

本项目是一个基于 WebRTC P2P 的多人视频聊天室，采用前后端分离架构。音视频数据不经过服务器，由客户端之间通过 WebRTC 直连传输；服务器仅负责 SDP 信令转发 与 房间管理。

仓库根目录包含两个版本：

目录	说明
版本1/	完整功能版：Express 后端 + Vue3 前端，含聊天、屏幕共享、设备切换、图片编辑、视频录制等
版本2/	精简版：独立 Vite 前端 + 轻量 Socket 服务端

本文档重点说明 版本1 的文件结构与运行环境。

---

版本1 技术栈

前端（版本1/vue3）

类别	技术
框架	Vue 3.3
语言	TypeScript 5
构建工具	Vite 4
状态管理	Pinia 2
UI 组件库	Ant Design Vue 4
实时通信	Socket.IO Client 4.7
样式	Sass / SCSS
其他	Vue JSX、mitt 事件总线、unplugin-vue-components 按需引入

后端（版本1/express）

类别	技术
运行时	Node.js
Web 框架	Express 4.18
实时通信	Socket.IO 4.7
中间件	body-parser
开发工具	nodemon、cross-env

---

运行环境

基础要求

项目	要求
Node.js	建议 16.x 及以上（推荐 18+ / 20+）
包管理器	npm / yarn / pnpm 均可
浏览器	支持 WebRTC 的现代浏览器（Chrome、Edge、Firefox、Safari 等）
操作系统	macOS / Windows / Linux

端口与网络

服务	默认端口	协议	说明
Express 后端	3000	开发环境 HTTP / 生产环境 HTTPS	Socket.IO 信令服务
Vue3 前端	5173（Vite 默认）	HTTP	开发服务器，通过代理访问后端

环境变量

前端（版本1/vue3/.env.development / .env.production）：

变量	说明
VITE_NODE_ENV	运行环境：development / production
VITE_DEV_MODE	是否开启开发者模式（开发环境）
VITE_APP_TITLE	应用标题
VITE_BASE_URL	API 基础路径，默认 /api

后端：

变量	说明
NODE_ENV	development 时使用 HTTP；非 development 时使用 HTTPS（需配置 SSL 证书）

开发代理

前端 vite.config.ts 已配置代理：

• /api → http://localhost:3000（REST 接口）
• /socket.io → http://localhost:3000（WebSocket 信令）

---

版本1 启动方式

需分别启动后端与前端两个服务。

1. 启动后端

cd 版本1/express
npm install
npm run start    # 等价于 npm run dev，使用 nodemon 热重载

启动成功后控制台输出：http://localhost:3000/

2. 启动前端

cd 版本1/vue3
npm install
npm run dev

浏览器访问 Vite 开发地址（通常为 http://localhost:5173）。

3. 生产构建（前端）

cd 版本1/vue3
npm run build      # 输出到 dist/
npm run preview    # 本地预览构建结果

---

版本1 架构说明

┌─────────────┐     Socket.IO 信令      ┌─────────────┐
│  Vue3 客户端 │ ◄──────────────────────► │ Express 服务端 │
│  (WebRTC)   │     offer/answer/ice     │  (房间管理)   │
└──────┬──────┘                          └─────────────┘
       │
       │  WebRTC P2P 直连（音视频 / 数据通道）
       ▼
┌─────────────┐
│  其他客户端  │
└─────────────┘

• 服务端：维护房间、用户列表，转发 WebRTC 信令（SDP、ICE Candidate），不转发媒体流。
• 客户端：封装 WebRTC SDK（src/utils/WebRTC/），实现 P2P 连接、屏幕共享、设备切换、断线重连等。

---

版本1 文件目录结构

版本1/
├── express/                          # 后端服务
│   ├── config/
│   │   └── database.js               # 内存数据存储（clients、rooms、userInfoMap）
│   ├── src/
│   │   ├── app.js                    # 应用入口，组装 Express + Router + Socket
│   │   ├── middlewares/
│   │   │   └── index.js              # 全局中间件（body-parser 等）
│   │   ├── router/
│   │   │   ├── index.js              # 路由自动注册（扫描 router 目录）
│   │   │   └── userRouter.js         # 用户相关 REST 接口
│   │   ├── services/
│   │   │   └── index.js              # Express 实例创建，定义 PORT=3000
│   │   └── utils/
│   │       ├── socket.js             # Socket.IO 核心：房间、信令、重连逻辑
│   │       └── util.js               # 工具函数（debounce 等）
│   ├── package.json
│   └── README.md                     # Socket 事件协议文档
│
└── vue3/                             # 前端应用
    ├── public/
    │   └── logo.svg                  # 静态资源
    ├── src/
    │   ├── main.ts                   # 应用入口：Pinia、自定义指令注册
    │   ├── App.vue                   # 根组件
    │   ├── style.css                 # 全局样式
    │   ├── assets/                   # 静态资源
    │   │   ├── emojis.ts             # 表情数据
    │   │   └── file-type/            # 文件类型图标（pdf、word、zip 等）
    │   ├── views/
    │   │   └── ChatRoom.vue          # 聊天室主页面
    │   ├── components/               # 业务组件
    │   │   ├── Layout.vue            # 页面布局
    │   │   ├── UserIcon.vue          # 用户头像
    │   │   ├── FileList.vue          # 文件列表
    │   │   ├── VideoRecorder.vue     # 视频录制
    │   │   ├── scrollbar.vue         # 滚动条
    │   │   ├── chat/                 # 聊天相关
    │   │   │   ├── Chat.vue          # 聊天面板
    │   │   │   ├── Emoji.vue         # 表情选择
    │   │   │   ├── MessageList.vue   # 消息列表
    │   │   │   └── MessageFile.vue   # 文件消息
    │   │   ├── chatroom/             # 房间相关
    │   │   │   ├── Join.vue          # 加入房间
    │   │   │   ├── MemberList.vue    # 成员列表
    │   │   │   └── DeviceSelect.vue  # 设备选择（摄像头/麦克风）
    │   │   ├── edit/                 # 图片编辑（TSX/JSX）
    │   │   │   ├── EditImage.tsx
    │   │   │   ├── EditImage.jsx
    │   │   │   └── utils.ts
    │   │   ├── preview/              # 图片预览
    │   │   │   └── PreviewImage.tsx
    │   │   └── menu/                 # 右键菜单
    │   │       └── menu.tsx
    │   ├── hooks/                    # 组合式函数
    │   │   ├── useMenu.ts            # 菜单逻辑
    │   │   ├── useVideoRecorder.ts   # 视频录制
    │   │   ├── useResizeObserver.ts  # 尺寸监听
    │   │   ├── useSlotRef.ts         # 插槽引用
    │   │   └── useWebWorkerFn.ts     # Web Worker 封装
    │   ├── store/                    # Pinia 状态管理
    │   │   ├── index.ts
    │   │   └── modules/
    │   │       └── chat.ts           # 聊天状态
    │   ├── styles/
    │   │   └── variables.scss        # SCSS 全局变量
    │   ├── test/                     # 功能测试/演示组件
    │   │   ├── AudioVisualizer.vue   # 音频可视化
    │   │   ├── Canvas.vue            # Canvas 测试
    │   │   ├── Clipboard.vue         # 剪贴板测试
    │   │   └── SpeechRecognition.vue # 语音识别测试
    │   └── utils/                    # 工具与核心 SDK
    │       ├── WebRTC/               # WebRTC 核心封装
    │       │   ├── rtc-client.ts     # RTC 客户端 SDK 入口
    │       │   ├── WebRTC.ts         # WebRTC 连接管理
    │       │   └── message.ts        # 信令消息定义
    │       ├── MediaDevices/
    │       │   └── mediaDevices.ts   # 媒体设备管理
    │       ├── audio/
    │       │   ├── audioVisualizer.ts
    │       │   └── speechRecognition.ts
    │       ├── Canvas/
    │       │   └── html2canvas.ts    # 截图
    │       ├── Clipboard/
    │       │   └── clipboard.ts      # 剪贴板
    │       ├── directive/            # Vue 自定义指令
    │       │   ├── index.ts
    │       │   ├── vEditImage.ts     # 图片编辑指令
    │       │   ├── vMenu.ts          # 右键菜单指令
    │       │   ├── vPreview.ts       # 图片预览指令
    │       │   └── vSelectFile.ts    # 文件选择指令
    │       ├── socket-client.ts      # Socket.IO 客户端封装
    │       ├── fileUtils.ts          # 文件处理
    │       ├── formatDate.ts         # 日期格式化
    │       ├── colorUtils.ts         # 颜色工具
    │       ├── event.ts              # 事件工具
    │       ├── message.ts            # 消息工具
    │       ├── observer.ts           # 观察者模式
    │       ├── queue.ts              # 队列
    │       └── util.ts               # 通用工具
    ├── types/
    │   └── global.d.ts               # 全局类型声明
    ├── index.html                    # HTML 入口
    ├── vite.config.ts                # Vite 配置（代理、别名、构建）
    ├── tsconfig.json                 # TypeScript 配置
    ├── tsconfig.node.json
    ├── components.d.ts               # 组件自动导入类型
    ├── .env.development              # 开发环境变量
    ├── .env.production               # 生产环境变量
    ├── package.json
    └── README.zh-CN.md               # 前端详细文档（含 RTCClient API）

---

版本1 核心模块说明

后端模块

文件	职责
src/app.js	启动入口，依次初始化中间件、路由、Socket
src/utils/socket.js	Socket.IO 事件处理：join/leave、offer/answer、icecandidate、reconnect
config/database.js	内存存储：clients（连接映射）、rooms（房间）、userInfoMap（用户信息）
src/router/userRouter.js	用户相关 HTTP 接口
src/services/index.js	创建 Express 实例，端口固定为 3000

前端模块

目录/文件	职责
views/ChatRoom.vue	聊天室主界面，整合视频、聊天、成员列表
utils/WebRTC/	WebRTC SDK，封装 P2P 连接、屏幕共享、设备切换、断线重连
utils/directive/	自定义指令：图片编辑、预览、右键菜单、文件选择
components/chatroom/	加入房间、成员管理、设备选择
components/chat/	文字/文件/表情消息
store/modules/chat.ts	聊天消息 Pinia 状态
hooks/useVideoRecorder.ts	视频录制 Hook

Socket 信令事件（前后端约定）

事件名	方向	说明
join	客户端 → 服务端	加入房间
leave	双向	离开房间
offer / answer	双向	WebRTC SDP 交换
icecandidate	双向	ICE 候选交换
getOffer	客户端 → 服务端	请求对端 offer
reconnect / reconnectWork	双向	断线重连
error	服务端 → 客户端	错误通知（如用户名重复）

详细协议见 版本1/express/README.md。

---

仓库根目录结构

online-video-chat---simple/
├── 项目说明.md          # 本文档
├── 版本1/               # 完整版（Express + Vue3）
│   ├── express/
│   └── vue3/
└── 版本2/               # 精简版（Vite + 轻量 Server）
    ├── src/
    ├── server/
    └── ...