mediasoup源码走读（二）环境搭建与 Demo 运行

Mediasoup 的环境搭建核心是 "依赖安装→编译 C++ 核心→配置 Demo→启动运行"，需重点关注 Node.js 版本兼容性、C++ 编译工具链安装。

2.1、环境准备（核心依赖）

Mediasoup 依赖 Node.js（运行时）、C++ 编译工具链（编译核心）、Python（辅助编译），三者版本必须匹配，否则会导致编译失败。

1. 核心依赖版本要求

依赖项	版本要求	作用说明
Node.js	v16.x LTS 或 v18.x LTS（推荐）	Mediasoup 不支持 v14 及以下、v20+ 部分版本（C++ 绑定兼容问题）
Python	v3.6+	node-gyp（Node.js C++ 模块编译工具）依赖 Python 解析配置
C++ 编译工具链	对应系统最新稳定版	编译 Mediasoup 的 C++ 核心（基于 libuv/FFmpeg 等底层库）

2. 分系统安装依赖

（1）Windows 系统（Win10/Win11）

安装 Node.js ：

从 Node.js 官网下载 v16.x LTS 安装包（如 node-v16.20.2-x64.msi），勾选"Add to PATH"，默认安装即可。

验证：打开 cmd 输入 node -v（显示 v16.x）、npm -v（显示 8.x）。
安装 C++ 编译工具链 ：

运行 cmd（管理员模式），执行以下命令（自动安装 Visual Studio Build Tools 2019，约 5GB 空间）：
bash 复制代码
```
npm install --global --production windows-build-tools@4.0.0
```
或手动下载：从 VS 官网安装"Visual Studio 生成工具"，勾选"C++ 生成工具"和"Windows 10 SDK"。
安装 Python ：

从 Python 官网下载 v3.9.x（兼容最佳），勾选"Add Python to PATH"，默认安装。

验证：cmd 输入 python --version（显示 3.9.x）。

（2）macOS 系统（macOS 12+）

安装 Node.js ：

用 Homebrew 安装（推荐）：
bash 复制代码
```
brew install node@16
```
验证：node -v（v16.x）、npm -v（8.x）。
安装 C++ 编译工具链 ：

安装 Xcode 命令行工具：
bash 复制代码
```
xcode-select --install
```
弹出安装窗口，点击"安装"（约 2GB 空间）。
安装 Python ：

macOS 自带 Python 2.7（不兼容），需安装 Python 3：
bash 复制代码
```
brew install python@3.9
```
验证：python3 --version（3.9.x）。

（3）Linux 系统（Ubuntu 20.04/22.04，CentOS 7+）

安装 Node.js ：

Ubuntu 示例（其他系统参考 Node.js 官网）：
bash 复制代码
```
# 导入 Node.js 源
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs
```
验证：node -v（v16.x）、npm -v（8.x）。
安装 C++ 编译工具链与 Python ：

Ubuntu：
bash 复制代码
```
sudo apt-get install -y build-essential python3 python3-pip
```
CentOS：
bash 复制代码
```
sudo yum install -y gcc-c++ make python3 python3-pip
```
验证：gcc --version（显示 9.x+）、python3 --version（3.6.x+）。

2.2、获取 Mediasoup 官方 Demo

Mediasoup 官方提供完整 Demo（含信令服务器、前端页面、Mediasoup 核心调用），直接克隆运行即可测试多人视频会议、屏幕共享等功能。

1. 克隆 Demo 仓库

打开终端/CMD，执行以下命令（需安装 Git，无 Git 可从官网安装）：

bash 复制代码

# 克隆官方 Demo 仓库
git clone https://github.com/versatica/mediasoup-demo.git
# 进入 Demo 目录
cd mediasoup-demo

2. 安装依赖（关键步骤：编译 C++ 核心）

Demo 分为 server（后端：Node.js+Mediasoup 核心）和 app（前端：React），需分别安装依赖：

（1）安装后端依赖（核心：编译 Mediasoup C++ 模块）

bash 复制代码

# 进入 server 目录
cd server
# 安装依赖（会自动编译 Mediasoup C++ 核心，耗时 5-10 分钟，需网络通畅）
npm install

关键说明：
- npm install 会触发 node-gyp rebuild，编译 Mediasoup 的 C++ 核心（依赖 FFmpeg/libuv 等）；
- 若网络慢导致编译失败，可设置 npm 淘宝镜像加速：
  bash 复制代码
```
npm config set registry https://registry.npm.taobao.org
npm config set disturl https://npm.taobao.org/dist
npm config set electron_mirror https://npm.taobao.org/mirrors/electron/
```
- 编译成功标志：终端显示 mediasoup@x.x.x install: node-gyp rebuild` 且无报错。

（2）安装前端依赖

bash 复制代码

# 回到 Demo 根目录
cd ..
# 进入 app 目录
cd app
# 安装前端依赖（React 相关）
npm install

2.3、Demo 配置（简单修改即可运行）

官方 Demo 的默认配置可直接本地运行，若需局域网/公网访问，需修改 server/config.js 中的关键参数：

1. 核心配置文件：server/config.js

用编辑器打开该文件，重点关注以下配置（其他保持默认）：

javascript 复制代码

module.exports = {
  // 1. 信令服务器配置（WebSocket）
  wsServer: {
    listenIp: '0.0.0.0', // 允许所有IP访问（本地/局域网/公网）
    listenPort: 3000,    // 信令服务器端口（默认3000，可修改）
  },

  // 2. Mediasoup Worker 配置（资源分配）
  mediasoup: {
    numWorkers: 1, // Worker 数量（建议 = CPU核心数，本地测试1个即可）
    worker: {
      rtcMinPort: 40000, // ICE 候选端口范围（需开放防火墙）
      rtcMaxPort: 49999,
    },
    // 3. 媒体流配置（编码/码率，默认适配多数终端）
    router: {
      mediaCodecs: [
        {
          kind: 'audio',
          mimeType: 'audio/opus',
          clockRate: 48000,
          channels: 2,
        },
        {
          kind: 'video',
          mimeType: 'video/VP8', // 视频编码（兼容所有浏览器）
          clockRate: 90000,
          parameters: {
            'x-google-start-bitrate': 1000, // 初始码率（1Mbps）
          },
        },
      ],
    },
  },
};

2. 配置说明（新手可跳过修改，直接用默认值）

listenIp: '0.0.0.0'：允许其他设备（如手机、另一台电脑）通过局域网 IP 访问 Demo；
rtcMinPort/rtcMaxPort：Mediasoup 用于音视频传输的端口范围，本地测试无需开放，局域网/公网需在防火墙中开放该端口段；
numWorkers：Worker 数量建议等于 CPU 核心数（如 8 核 CPU 设为 8），提升并发性能。

2.4、启动 Demo 并测试

1. 启动后端（信令服务器+Mediasoup 核心）

bash 复制代码

# 确保当前在 server 目录下
cd mediasoup-demo/server
# 启动后端（默认端口 3000）
npm start

启动成功标志：终端显示以下日志（无报错）：

复制代码

mediasoup-demo:server starting WebSocket server on ws://0.0.0.0:3000
mediasoup-demo:server creating mediasoup Worker #1
mediasoup-demo:server mediasoup Worker #1 started

2. 启动前端（React 页面）

打开 新的终端/CMD，执行以下命令：

bash 复制代码

# 进入 app 目录
cd mediasoup-demo/app
# 启动前端（默认端口 3001）
npm start

启动成功后，会自动打开浏览器，访问地址：http://localhost:3001；
若未自动打开，手动输入 http://localhost:3001 即可。

3. 测试功能（多人视频会议）

（1）本地测试（单设备多窗口）

浏览器打开 http://localhost:3001，输入房间号（如 test123）和用户名（如 user1），点击"JOIN"；
允许浏览器访问麦克风和摄像头（必须授权，否则无法推流）；
再打开 2-3 个浏览器窗口，输入相同房间号、不同用户名，加入房间；
此时可看到多个"自己"的视频窗口，实现多人视频通话，支持：
- 静音/开麦、关闭/打开摄像头；
- 屏幕共享（点击"Share Screen"）；
- 聊天消息（右侧输入框发送文本，基于 DataChannel 实现）。

（2）局域网测试（多设备）

查看运行 Demo 的设备 IP（如 Windows 用 ipconfig，macOS/Linux 用 ifconfig，获取局域网 IP 如 192.168.1.100）；
另一台设备（手机/电脑）连接同一 WiFi，浏览器输入 http://192.168.1.100:3001；
输入相同房间号，加入后即可实现跨设备视频通话。

（3）核心功能验证

功能	操作方式	验证标准
音视频通话	多设备加入同一房间，授权音视频权限	能看到对方视频、听到对方声音，延迟低（10-30ms）
屏幕共享	点击"Share Screen"，选择共享窗口/桌面	其他参会人能看到共享内容，无明显卡顿
数据通道（聊天）	右侧输入框发送文本，点击发送	所有参会人能收到消息，实时同步
弱网适配	限制网络带宽（如用 4G 热点）	视频自动降清，无卡顿，音频保持流畅

2.5、常见问题排查（避坑指南）

1. 安装依赖时编译失败（最常见）

报错特征：

终端显示 node-gyp rebuild 失败、gyp ERR!、compile error 等。

解决方案：

检查 Node.js 版本：必须是 v16.x LTS 或 v18.x LTS，其他版本兼容性差；
检查 C++ 编译工具链：Windows 需安装 Visual Studio Build Tools，macOS 需安装 Xcode 命令行工具，Linux 需安装 build-essential；
检查 Python 版本：必须是 v3.6+，且 python 命令指向 Python 3（Windows 用 python --version，macOS/Linux 用 python3 --version）；
网络问题：设置 npm 淘宝镜像后重新安装依赖。

2. 启动前端后无法访问（端口占用）

报错特征：

终端显示 Error: listen EADDRINUSE: address already in use :::3001。

解决方案：

关闭占用 3001 端口的程序，重新启动前端；
或修改前端端口：打开 app/package.json，修改 scripts.start 为 PORT=3002 react-scripts start（改为 3002 端口），然后访问 http://localhost:3002。

3. 加入房间后无视频/声音

可能原因：

未授权浏览器访问麦克风/摄像头：刷新页面，重新授权；
防火墙拦截音视频端口：本地测试无需处理，局域网/公网需开放 rtcMinPort/rtcMaxPort（40000-49999）；
编码不兼容：Demo 默认用 VP8 编码，部分老旧浏览器不支持，换用 Chrome/Firefox/Edge 最新版。

4. 局域网设备无法访问 Demo

解决方案：

确保所有设备连接同一 WiFi/局域网；
运行 Demo 的设备需关闭防火墙（或开放 3000 端口、40000-49999 端口段）；
访问时用局域网 IP 而非 localhost（如 http://192.168.1.100:3001）。