video_socket-server/.qoder/repowiki/zh/content/开发指南/开发环境搭建.md

# 开发环境搭建

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [client/package.json](file://client/package.json)
- [tsconfig.json](file://tsconfig.json)
- [tsconfig.build.json](file://tsconfig.build.json)
- [tsconfig.lint.json](file://tsconfig.lint.json)
- [jest.config.js](file://jest.config.js)
- [client/jest.config.js](file://client/jest.config.js)
- [.eslintrc.cjs](file://.eslintrc.cjs)
- [client/.eslintrc.json](file://client/.eslintrc.json)
- [run.bat](file://run.bat)
- [src/index.ts](file://src/index.ts)
- [src/server.ts](file://src/server.ts)
- [client/jest.setup.js](file://client/jest.setup.js)
- [.gitignore](file://.gitignore)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向首次参与“视频流服务器”项目的开发者，目标是帮助你在本地快速完成开发环境搭建与运行。内容涵盖：
- Node.js 版本要求与安装步骤（含 LTS 建议）
- TypeScript 编译与构建配置说明
- 包管理器选择建议（npm 与 yarn）
- 依赖安装流程（生产依赖与开发依赖）
- 开发脚本详解（dev、build、test 等）
- IDE 配置建议（VS Code 插件与调试）
- 常见环境问题排查与解决方案

## 项目结构
该项目采用前后端分离的多包结构：
- 根包：服务端逻辑与构建、测试、打包配置
- 客户端子包：前端示例页面与测试配置

```mermaid
graph TB
Root["根项目<br/>package.json"] --> TS["TypeScript 配置<br/>tsconfig*.json"]
Root --> JestRoot["Jest 根测试配置<br/>jest.config.js"]
Root --> ESLintRoot[".eslintrc.cjs"]
Root --> RunBat["启动批处理<br/>run.bat"]
Client["客户端子包<br/>client/package.json"] --> JestClient["Jest 客户端测试配置<br/>client/jest.config.js"]
Client --> ESLintClient["ESLint 客户端规则<br/>client/.eslintrc.json"]
Client --> Public["静态资源<br/>client/public/*"]
Root --> Src["服务端源码<br/>src/*"]
Src --> IndexTS["入口与参数解析<br/>src/index.ts"]
Src --> ServerTS["HTTP 服务与路由<br/>src/server.ts"]
```

图表来源
- [package.json:1-60](file://package.json#L1-L60)
- [client/package.json:1-19](file://client/package.json#L1-L19)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [client/jest.config.js:1-196](file://client/jest.config.js#L1-L196)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [client/.eslintrc.json:1-23](file://client/.eslintrc.json#L1-L23)
- [run.bat:1-17](file://run.bat#L1-L17)
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)

章节来源
- [package.json:1-60](file://package.json#L1-L60)
- [client/package.json:1-19](file://client/package.json#L1-L19)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [client/jest.config.js:1-196](file://client/jest.config.js#L1-L196)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
- [client/.eslintrc.json:1-23](file://client/.eslintrc.json#L1-L23)
- [run.bat:1-17](file://run.bat#L1-L17)
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)

## 核心组件
- Node.js 运行时与包管理器：用于安装依赖、执行脚本、启动服务
- TypeScript 编译系统：将 ts/ts 文件编译为 js 并输出到 build 目录
- 测试框架：Jest（服务端）与 Jest + jsdom（客户端）
- 代码质量工具：ESLint（TS 规则与 Jest 插件）
- 启动与打包：npm scripts 提供 dev/build/test/start/newman/pack 等命令；pkg 用于打包

章节来源
- [package.json:5-13](file://package.json#L5-L13)
- [client/package.json:5-8](file://client/package.json#L5-L8)
- [tsconfig.json:4-11](file://tsconfig.json#L4-L11)
- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
- [tsconfig.lint.json:4-11](file://tsconfig.lint.json#L4-L11)
- [jest.config.js:174-176](file://jest.config.js#L174-L176)
- [client/jest.config.js:139-144](file://client/jest.config.js#L139-L144)
- [.eslintrc.cjs:6-11](file://.eslintrc.cjs#L6-L11)
- [client/.eslintrc.json:3-6](file://client/.eslintrc.json#L3-L6)

## 架构总览
下图展示了从开发脚本到服务启动的关键路径，以及静态资源与 API 的组织方式。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant NPM as "npm 脚本"
participant TS as "TypeScript 编译器"
participant Node as "Node 进程"
participant Express as "Express 应用"
participant Static as "静态资源"
participant Client as "浏览器客户端"
Dev->>NPM : 执行 "npm run dev"
NPM->>TS : 使用 ts-node 直接执行 src/index.ts
TS-->>Node : 返回可执行的 Node 入口
Node->>Express : 初始化应用与中间件
Express->>Static : 挂载静态目录 client/public
Express-->>Dev : 输出监听地址与模式信息
Client->>Express : 访问 / 与 /config
Express-->>Client : 返回示例页面与配置
```

图表来源
- [package.json:10](file://package.json#L10)
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)

章节来源
- [package.json:5-13](file://package.json#L5-L13)
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)

## 详细组件分析

### Node.js 与包管理器
- 版本要求与 LTS 建议
  - 项目使用 TypeScript 4.8.x 与 Jest 29.x 等较新生态，建议优先选择 Node.js LTS（长期支持版本），以获得更稳定的依赖兼容性与社区支持。
  - 若需使用实验特性（如客户端测试中的 ES Module），可考虑使用当前稳定版 Node.js，但请确保团队统一版本。
- 包管理器选择
  - 推荐使用 npm（项目未指定 yarn.lock，且 package.json 中未声明 yarn 专属配置）。
  - 如团队已有 yarn 工作流，也可继续使用，但需注意切换时清理 node_modules 并重新安装，避免锁文件冲突。

章节来源
- [package.json:28-46](file://package.json#L28-L46)
- [client/package.json:9-16](file://client/package.json#L9-L16)

### TypeScript 配置与构建
- 编译目标与输出
  - 目标：ES5（target），模块：CommonJS（module），输出目录：build（outDir），根目录：src（rootDir）。
  - 适用于 Node.js 运行时的通用兼容性与打包工具链。
- 构建配置
  - 标准配置：tsconfig.json
  - 构建专用配置：tsconfig.build.json 继承标准配置，仅包含 src/**/*。
  - Lint 专用配置：tsconfig.lint.json，关闭 sourceMap，便于 ESLint 解析。
- 关键编译脚本
  - build：通过 tsc -p tsconfig.build.json 执行构建。
  - dev：通过 ts-node 直接运行 src/index.ts，无需预先编译。
  - lint：通过 ESLint 对 src 与 test 下的 TS 文件进行检查。

```mermaid
flowchart TD
Start(["开始"]) --> LoadTS["加载 tsconfig.json"]
LoadTS --> ExtendBuild["继承 tsconfig.build.json"]
ExtendBuild --> Compile["执行 tsc 编译 src/**/*"]
Compile --> OutDir["输出至 build 目录"]
OutDir --> End(["结束"])
```

图表来源
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
- [tsconfig.lint.json:1-12](file://tsconfig.lint.json#L1-L12)

章节来源
- [tsconfig.json:4-11](file://tsconfig.json#L4-L11)
- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
- [tsconfig.lint.json:4-11](file://tsconfig.lint.json#L4-L11)
- [package.json:6-7](file://package.json#L6-L7)
- [package.json:11](file://package.json#L11)

### 依赖安装与分类
- 生产依赖（dependencies）
  - 包括 express、ws、cors、morgan、multer、uuid、swagger-* 等，用于服务端运行期功能。
- 开发依赖（devDependencies）
  - 包括 TypeScript、ts-node、jest、ts-jest、eslint 及其插件、pkg 等，用于开发、测试与打包。
- 客户端子包
  - 客户端 package.json 为独立的开发环境，包含 eslint、jest、jsdom 等测试相关依赖。

章节来源
- [package.json:14-27](file://package.json#L14-L27)
- [package.json:28-46](file://package.json#L28-L46)
- [client/package.json:9-16](file://client/package.json#L9-L16)

### 开发脚本详解
- dev：使用 ts-node 直接运行 src/index.ts，支持热调试与快速迭代。
- build：调用 tsc 按 tsconfig.build.json 编译生成 build。
- test：运行 Jest 测试，收集覆盖率，服务端测试位于 test/*.ts。
- start：启动已编译的服务端进程，支持 HTTPS 参数与日志级别。
- lint：使用 ESLint 检查 TS 与测试代码。
- pack：使用 pkg 将项目打包为可执行文件（targets 指向 node10）。
- newman：执行 Postman 集合进行接口测试（需要 Newman）。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant NPM as "npm 脚本"
participant Jest as "Jest"
participant ESLint as "ESLint"
participant TSC as "TypeScript 编译器"
participant Pkg as "pkg 打包器"
Dev->>NPM : npm run test
NPM->>Jest : 执行测试与覆盖率收集
Jest-->>Dev : 输出测试结果
Dev->>NPM : npm run lint
NPM->>ESLint : 检查 src 与 test 下 TS 文件
ESLint-->>Dev : 输出规则警告/错误
Dev->>NPM : npm run build
NPM->>TSC : tsc -p tsconfig.build.json
TSC-->>Dev : 生成 build 目录
Dev->>NPM : npm run pack
NPM->>Pkg : 打包为可执行文件
Pkg-->>Dev : 输出二进制产物
```

图表来源
- [package.json:5-13](file://package.json#L5-L13)
- [jest.config.js:174-176](file://jest.config.js#L174-L176)
- [.eslintrc.cjs:6-11](file://.eslintrc.cjs#L6-L11)
- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)

章节来源
- [package.json:5-13](file://package.json#L5-L13)
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)

### 客户端测试与环境配置
- 客户端 Jest 配置
  - 测试环境：jest-environment-jsdom
  - 超时时间：5000ms
  - setupFilesAfterEnv：引入 client/jest.setup.js，注入 fetch、TextEncoder/Decoder、RTCPeerConnection 等浏览器 API 的 polyfill。
- 客户端 ESLint
  - 推荐规则：eslint:recommended、plugin:jest/recommended
  - 环境：browser、es6、jest
  - 规则：分号强制与多余分号报错。

章节来源
- [client/jest.config.js:139-144](file://client/jest.config.js#L139-L144)
- [client/jest.config.js:130](file://client/jest.config.js#L130)
- [client/jest.setup.js:1-35](file://client/jest.setup.js#L1-L35)
- [client/.eslintrc.json:1-23](file://client/.eslintrc.json#L1-L23)

### 服务端启动与静态资源
- 启动流程
  - 通过 src/index.ts 解析命令行参数（端口、HTTPS、密钥证书、信令类型、通信模式、日志级别等），创建 Express 应用并启动 HTTP/HTTPS 服务。
  - 根据模式输出监听地址与模式信息。
- 静态资源与 API
  - 挂载 client/public 为静态目录，根路径返回示例页面。
  - 提供 /config 接口返回当前配置。
  - 提供 /signaling 路由（由 signaling 模块处理）。
  - 提供头像上传 API 与 /uploads 静态目录。

```mermaid
flowchart TD
A["启动 src/index.ts"] --> B["解析参数与选项"]
B --> C{"是否启用 HTTPS"}
C --> |是| D["读取 server.key 与 server.cert"]
C --> |否| E["使用 HTTP 监听"]
D --> F["创建 HTTPS 服务器"]
E --> G["创建 HTTP 服务器"]
F --> H["初始化 Express 应用"]
G --> H
H --> I["挂载静态资源 client/public"]
H --> J["注册 /config 与 /signaling 路由"]
H --> K["启动 Swagger 文档"]
H --> L["启动头像上传与 /uploads"]
```

图表来源
- [src/index.ts:14-109](file://src/index.ts#L14-L109)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)

章节来源
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)

### IDE 配置建议（VS Code）
- 推荐扩展
  - ESLint：实时语法与风格检查
  - Jest Runner：一键运行/调试单个或全部测试
  - TypeScript Importer：自动导入 TS 模块
  - Prettier：格式化（配合 ESLint 规则）
  - Thunder Client 或 REST Client：HTTP 请求调试
- 调试配置（launch.json）
  - 启动服务端：使用 Node 调试器附加到 ts-node 进程，或直接调试已编译的 build/index.js。
  - 启动客户端：在浏览器中打开 client/public 下的示例页面，结合断点与网络面板调试。
- 设置同步
  - .vscode/settings.json 与 .vscode/tasks.json、.vscode/launch.json 由 .gitignore 排除，可在本地按需添加。

章节来源
- [.gitignore:175-181](file://.gitignore#L175-L181)

## 依赖关系分析
- 内部依赖
  - src/index.ts 依赖 src/server.ts 与 src/websocket（通过导入）。
  - src/server.ts 依赖 signaling、swagger、multer 等模块。
- 外部依赖
  - 生产依赖：express、ws、cors、morgan、multer、uuid、swagger-*。
  - 开发依赖：TypeScript、ts-node、jest、ts-jest、eslint、pkg 等。
- 客户端依赖
  - eslint、jest、jest-environment-jsdom、node-fetch 等。

```mermaid
graph LR
Index["src/index.ts"] --> Server["src/server.ts"]
Server --> Signaling["signaling 模块"]
Server --> Swagger["swagger 初始化"]
Server --> Multer["文件上传处理"]
Index --> WS["WebSocket 信令"]
RootPkg["根 package.json"] --> Deps["生产依赖"]
RootPkg --> DevDeps["开发依赖"]
ClientPkg["client/package.json"] --> ClientDeps["客户端测试依赖"]
```

图表来源
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
- [package.json:14-46](file://package.json#L14-L46)
- [client/package.json:9-16](file://client/package.json#L9-L16)

章节来源
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
- [package.json:14-46](file://package.json#L14-L46)
- [client/package.json:9-16](file://client/package.json#L9-L16)

## 性能考虑
- 构建与缓存
  - 使用 TypeScript 编译缓存（tsbuildinfo）减少增量编译时间。
  - 在 CI 环境中复用 node_modules，避免重复下载。
- 测试性能
  - Jest 默认并发运行测试，可通过 maxWorkers 控制（已在配置中注释）。
  - 使用覆盖率收集时关注 I/O，必要时拆分测试集。
- 服务端性能
  - 静态资源由 Express 直接提供，建议在生产环境前移至 CDN 或反向代理。
  - 日志级别可调整为 none 以降低开销（通过 start 脚本参数）。

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 无法找到 node_modules 或依赖缺失
  - 清理缓存并重新安装：删除 node_modules 与 lockfile 后重新安装。
  - 确认包管理器一致性（npm/yarn），避免混用导致锁文件冲突。
- 启动失败（端口占用）
  - 修改端口或释放占用端口（默认 8080）。
- HTTPS 启动失败
  - 确认 server.key 与 server.cert 存在且可读。
  - 使用 start 脚本时传入正确的密钥与证书路径。
- 浏览器控制台缺少 API
  - 客户端测试需注入 polyfill，确认 jest.setup.js 已被加载。
- ESLint 报错
  - 使用 tsconfig.lint.json 作为 ESLint 的 parserOptions.project，确保规则解析正确。
- 覆盖率未生成
  - 确认 Jest 配置中的 collectCoverage 与 coverageDirectory 设置。
- Windows 批处理异常
  - run.bat 中包含注释与非执行语句，建议仅保留必要命令（如先 build 再 start）。

章节来源
- [.gitignore:35-51](file://.gitignore#L35-L51)
- [package.json:9](file://package.json#L9)
- [src/index.ts:55-66](file://src/index.ts#L55-L66)
- [client/jest.setup.js:1-35](file://client/jest.setup.js#L1-L35)
- [.eslintrc.cjs:13-16](file://.eslintrc.cjs#L13-L16)
- [jest.config.js:20](file://jest.config.js#L20)
- [run.bat:1-7](file://run.bat#L1-L7)

## 结论
按照本指南完成 Node.js、TypeScript、ESLint、Jest 与包管理器的配置后，你即可顺利运行与开发该视频流服务器项目。建议在团队内统一 Node.js 版本与包管理器，遵循 ESLint 规则与测试规范，以保证代码质量与协作效率。

[本节为总结，不直接分析具体文件]

## 附录
- 快速验证清单
  - 安装 Node.js LTS（或稳定版）
  - 使用 npm 安装依赖
  - 运行 npm run build 与 npm run dev
  - 执行 npm run test 与 npm run lint
  - 如需打包，运行 npm run pack

[本节为补充说明，不直接分析具体文件]