392 lines
16 KiB
Markdown
392 lines
16 KiB
Markdown
# 开发环境搭建
|
||
|
||
<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
|
||
|
||
[本节为补充说明，不直接分析具体文件] |