搭建 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++ 编译工具链	对应操作系统下的最新稳定版本	用于编译基于 libuv、FFmpeg 等底层库的 Mediasoup C++ 核心模块

2. 不同操作系统的依赖安装方法

（1）Windows 系统（Win10 / Win11）

安装 Node.js：
访问 Node.js 官网 下载 v16.x LTS 版本的安装包（例如：

node-v16.20.2-x64.msi

），安装过程中请勾选“Add to PATH”选项，其余保持默认设置即可完成安装。
验证安装： 打开命令提示符（cmd），输入以下命令：

node -v

应显示 Node.js 版本为 v16.x；再输入：

npm -v

应显示 npm 版本为 8.x 左右。

安装 C++ 编译工具链：
以管理员身份打开 cmd，执行以下命令（将自动安装 Visual Studio Build Tools 2019，占用约 5GB 存储空间）：

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

应输出 Python 版本信息，如 3.9.x。

（2）macOS 系统（macOS 12+）

安装 Node.js：
推荐使用 Homebrew 进行安装：

brew install node@16

验证安装： 输入以下命令查看版本：

node -v

应显示 v16.x；输入：

npm -v

应显示对应的 npm 版本（通常为 8.x）。

安装 C++ 编译工具链：
通过终端安装 Xcode 命令行工具：

xcode-select --install

系统会弹出安装窗口，点击“安装”按钮继续（预计占用约 2GB 空间）。

安装 Python：
macOS 自带的 Python 2.7 不满足需求，需额外安装 Python 3：

brew install python@3.9

验证安装： 输入：

python3 --version

应显示 Python 3.9.x 版本信息。

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

安装 Node.js（以 Ubuntu 为例）：
其他发行版可参考 Node.js 官网 提供的安装指南：

# 导入 Node.js 软件源
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs

验证安装： 执行：

node -v

确认 Node.js 为 v16.x；再执行：

npm -v

确认 npm 版本正确。

安装 C++ 编译工具链与 Python：
对于 Ubuntu 用户：

sudo apt-get install -y build-essential python3 python3-pip

对于 CentOS 用户：

sudo yum install -y gcc-c++ make python3 python3-pip

验证安装： 输入：

gcc --version

应显示 g++ 或 gcc 版本为 9.x 以上；输入：

python3 --version

应显示 Python 3.6 或更高版本。

2.2 获取并运行官方 Demo 项目

Mediasoup 提供了完整的示例项目，包含信令服务器、前端页面及核心 API 调用逻辑。通过该 Demo 可快速测试多人视频通话、屏幕共享等功能。

1. 克隆官方 Demo 仓库

在终端或 CMD 中执行以下命令（若未安装 Git，请先从其官网下载并安装）：

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

2. 安装项目依赖（重点：C++ 模块编译）

Demo 项目分为两个部分：

server

（后端服务：基于 Node.js 和 Mediasoup 核心）
和

app

（前端界面：采用 React 构建），需分别进入目录安装依赖。

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

# 进入 server 目录
cd server
# 安装依赖（此过程将自动编译 Mediasoup 的 C++ 核心模块，耗时约 5–10 分钟，需保证网络畅通）
npm install

关键说明：
执行此命令时，系统会触发：

npm install

进而调用：

node-gyp rebuild

2.3 Demo 配置（简单调整即可运行）

官方提供的 Demo 默认配置已支持本地运行。若需在局域网或公网环境下访问，需对关键参数进行适当修改。

核心配置文件位置如下：

server/config.js

使用任意文本编辑器打开该文件，重点关注以下几项设置，其余保持默认即可：

module.exports = {
  // 1. 信令服务器配置（基于 WebSocket）
  wsServer: {
    listenIp: '0.0.0.0',   // 允许所有 IP 接入，支持本地、局域网及公网访问
    listenPort: 3000,      // WebSocket 监听端口，默认为 3000，可根据需要更改
  },

  // 2. Mediasoup Worker 资源配置
  mediasoup: {
    numWorkers: 1,         // Worker 进程数量，建议设置为 CPU 核心数；本地测试设为 1 即可
    worker: {
      rtcMinPort: 40000,   // ICE 候选端口起始值
      rtcMaxPort: 49999,   // ICE 候选端口结束值，需确保防火墙开放此范围
    },
  },

  // 3. 媒体流编码与码率配置（适配大多数终端设备）
  router: {
    mediaCodecs: [
      {
        kind: 'audio',
        mimeType: 'audio/opus',
        clockRate: 48000,
        channels: 2,
      },
      {
        kind: 'video',
        mimeType: 'video/VP8', // VP8 编码兼容性广，适用于所有主流浏览器
        clockRate: 90000,
        parameters: {
          'x-google-start-bitrate': 1000, // 初始视频码率为 1 Mbps
        },
      },
    ],
  },
};

配置说明（初学者可跳过，直接使用默认值）

• listenIp: '0.0.0.0'

  ：将监听地址设为 0.0.0.0 后，允许局域网内其他设备（如手机或其他电脑）通过本机 IP 访问 Demo 页面。

• rtcMinPort/rtcMaxPort

  ：Mediasoup 使用指定端口段（40000–49999）进行音视频数据传输。本地测试无需额外操作；若部署在局域网或公网环境，需在系统防火墙中放行该端口区间。

• numWorkers

  ：Worker 数量建议与 CPU 核心数一致（例如 8 核 CPU 可设为 8），有助于提升并发处理能力与服务稳定性。

2.4 启动 Demo 并进行功能测试

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

确保当前所在目录为 server 目录：

cd mediasoup-demo/server

执行启动命令：

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 构建的用户界面）

打开一个新的终端或命令行窗口，执行以下操作：

cd mediasoup-demo/app
npm start

前端服务启动成功后，浏览器将自动打开并跳转至以下地址：

http://localhost:3001

若未自动打开，请手动在浏览器中访问该地址。

3. 功能测试：实现多人视频会议

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

1. 在浏览器中访问

   http://localhost:3001

   ；
2. 输入房间号（例如：

   test123

   ）和用户名（例如：

   user1

   ），点击“JOIN”按钮；
3. 授权浏览器访问麦克风与摄像头权限（必须允许，否则无法推流）；
4. 再打开 2–3 个新的浏览器标签页，使用相同的房间号但不同用户名加入同一房间；
5. 此时将看到多个本地视频窗口，模拟多人通话场景，支持以下交互功能：

• 静音 / 取消静音（麦克风控制）
• 关闭 / 开启摄像头
• 屏幕共享（点击“Share Screen”按钮触发）
• 文字聊天（通过右侧输入框发送消息，基于 WebRTC DataChannel 实现）

（2）局域网测试（跨设备连接）

1. 获取运行 Demo 的主机 IP 地址：
   • Windows 系统可使用命令：

     ipconfig

   • macOS 或 Linux 系统可使用：

     ifconfig

   • 获取到的局域网 IP 示例为：

     192.168.1.100

2. 确保其他设备（如手机或其他电脑）连接在同一 WiFi 网络下；
3. 在目标设备的浏览器中输入：

   http://192.168.1.100:3001

   ；
4. 输入相同房间号，即可加入会议，实现跨设备音视频通信。

（3）核心功能验证表

功能	操作方式	验证标准
音视频通话	多个设备加入同一房间，并授予音视频权限	能清晰看到对方画面，听到声音，端到端延迟控制在 10–30ms 内
屏幕共享	点击界面上的“Share Screen”按钮开始共享	其他参与者可实时观看共享者的屏幕内容，无明显卡顿或延迟

2.1 编译 Mediasoup C++ 核心模块

Mediasoup 的核心由 C++ 编写，构建时依赖 FFmpeg、libuv 等底层库。请确保开发环境已安装相关依赖。

若因网络原因导致编译失败（特别是在执行 node-gyp rebuild 时），可配置 npm 使用淘宝镜像源加速下载：

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/

编译成功的标志是在终端中出现 node-gyp rebuild 命令执行过程且全程无报错信息。

mediasoup@x.x.x install:

2.2 安装前端依赖包

完成核心编译后，进入前端项目目录以安装所需依赖：

# 返回 Demo 根目录
cd ..
# 进入 app 子目录
cd app
# 安装 React 相关依赖
npm install

server/config.js

共享屏幕操作：

点击“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. 加入房间后没有视频或音频输出

可能原因及处理方式：

• 浏览器未授予麦克风或摄像头权限 —— 可尝试刷新页面并重新允许相关设备访问；
• 防火墙阻止了音视频通信端口 —— 本地测试可忽略此问题，但在局域网或公网部署时需开放 UDP 端口范围
  

  rtcMinPort/rtcMaxPort

  （40000-49999）；
• 编码格式不兼容 —— 当前 Demo 默认采用 VP8 编码，部分老旧浏览器可能不支持，建议使用最新版 Chrome、Firefox 或 Edge 浏览器。

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

解决办法：

• 确保所有设备处于同一 WiFi 或局域网环境中；
• 运行 Demo 的主机应关闭防火墙，或手动开放 3000 端口以及 40000-49999 端口段；
• 访问时请使用主机的局域网 IP 地址，而非
  

  localhost

  
  （例如使用类似
  

  http://192.168.1.100:3001

  
  的形式进行访问）。