uni-app 集成音视频 SDK 全攻略：30 分钟搭建跨端视频通话功能

在跨端开发场景中，uni-app 凭借"一次开发、多端部署"的优势成为众多开发者的首选，而音视频通话功能则是社交、教育、会议等场景的核心需求。本文将结合即构SDK的特性，为大家带来 uni-app 集成音视频 SDK 的完整教程，助力开发者在 30 分钟内快速搭建跨端视频通话功能。

即构SDK具备低延迟、高并发、跨平台兼容等优势，可完美适配 uni-app 支持的 iOS、Android、H5、小程序等多端场景，同时提供完善的音视频处理能力和简洁的 API 接口，极大降低跨端音视频开发门槛。

一、前期准备：3 分钟完成环境与资源配置

1. 准备环境

在运行示例源码前，请确保开发环境满足以下要求：
1.1前提条件

已在 ZEGO 控制台创建项目，并申请有效的 AppID、AppSign 或 Token，详情请参考控制台 - 项目管理中的"项目信息"。
1.2.示例源码目录结构

下列结构为工程目录的文件结构，下文所涉及的文件路径均为相对于此目录的路径。

复制代码

.
├── App.vue
├── common
│   ├── uni-nvue.css          # uni 定义的 css样式
│   └── zego-nvue.css         # zego 定义的 css 样式
├── components
│   ├── uni-list
│   │   └── uni-list.vue
│   ├── uni-list-item
│   │   └── uni-list-item.vue
│   ├── uni-section
│   │   └── uni-section.vue
│   ├── uni-segmented-control
│   │   └── uni-segmented-control.vue
│   └── zego-ZegoExpressUniApp-JS        # zego uniapp sdk js 封装层
│       ├── lib                          # js 库文件
│       └── zego-view                    # 原生渲染 view
├── main.js
├── manifest.json
├── nativeplugins
│   └── zego-ZegoExpressUniAppSDK        # 本地依赖的 zego 原生插件
│       ├── android
│       ├── ios
│       └── package.json
├── package.json
├── pages                                # demo 源码
│   ├── KeyCenter.js                     # 在里面的 KeyCenter.java 文件中填写申请的 AppID、AppSign、Token
│   ├── example
│   │   ├── advance-stream               # 推拉流进阶
│   │   ├── advance-video                # 视频进阶
│   │   ├── common-feature               # 通用功能
│   │   ├── other                        # 其他功能
│   │   ├── quick-start                  # 快速开始
│   │   ├── scenes                       # 场景方案
│   │   └── setting                      # 设置与调试
│   ├── index
│   │   └── index.vue
│   └── permission.js
├── pages.json                           # 显示的所有页面
├── static                               # 资源文件
│   ├── SampleVideo_1280x720_5mb.mp4
│   └── logo.png
├── uni.scss
└── unpackage                            # uniapp 打包生成的文件

运行示例代码：

使用 HBuilder X 工具打开示例工程。
示例源码中缺少 SDK 初始化所需的 AppID、AppSign 或 Token，需要修改 "pages/KeyCenter.js" 文件，请使用本文"前提条件"已获取的 AppID、AppSign 或 Token 正确填写，否则示例源码无法正常运行。

如果您是基于 iOS、Android 原生平台开发，选择了 AppSign 鉴权，将 Token 传空即可。
如果您选择使用Token 鉴权，将 AppSign 传空即可。

找到项目目录下的 manifest.json 文件，修改 "uni-app" 应用标识。
在项目中导入插件，具体操作请参考在 uni-app 项目中导入插件。
运行代码。
web端→

体验实时音视频功能

在真机中运行项目，运行成功后，可以看到本端视频画面。

为方便体验，ZEGO 提供了一个 Web 端调试示例，在该页面下，输入相同的 AppID、RoomID，输入不同的 UserID、以及对应的 Token，即可加入同一房间与真机设备互通。当成功开始音视频通话时，可以听到远端的音频，看到远端的视频画面。

二、核心集成：20 分钟完成音视频通话核心功能搭建

（一）集成SDK

1. 准备环境

在开始集成 ZEGO Express SDK 前，请确保开发环境满足以下要求：

HBuilderX 3.0.0 或以上版本。
App:
- 准备 iOS 及 Android 设备，版本要求如下：
  - iOS 12.0或以上版本且支持音视频的 iOS 设备。
  - Android 4.4 或以上版本且支持音视频的 Android 设备。
- iOS 及Android 设备已经连接到 Internet。
Web:
- 准备一台可以连接到互联网的 Windows 或 macOS 计算机。
- 使用最新版本的 Chrome 浏览器。

2. 集成 SDK-创建项目（此步骤以如何创建新项目为例，如果是集成到已有项目，可忽略此步）

启动 HBuilderX，选择"文件 > 新建 > 项目"菜单

3. 在出现的表单中，选择 "uni-app" 平台，并填写项目名称，单击"创建"，即可创建项目。

3.集成 SDK

复制代码

 注意 ：uni-app SDK 视频相关的画面是基于原生 view 进行渲染的，只能使用 nvue。

方式 1：在 ZEGO 官网下载 SDK

下载 Express-Video SDK 到本地，解压缩 "zego-ZegoExpressUniAppSDK" 文件。
将解压缩后的文件夹，直接复制到项目工程根目录下的 "nativeplugins" 文件夹中，如果没有该目录，请手动创建。

方式 2：通过 uni-app 插件市场获取 Express-Video SDK。
在 uni-app 插件市场任选一种方式导入：
方式 1：单击 "购买（0元） for 云打包"，选择相应的项目导入。
方式 2：单击 "下载 for 离线打包"，离线导入。

下载 SDK 到本地，解压缩 "zego-ZegoExpressUniAppSDK" 文件。将解压缩后的文件夹，直接复制到项目工程根目录下的 "nativeplugins" 文件夹中，如果没有该目录，请手动创建。

4. 在 uni-app 项目中导入插件

4.1 单击项目目录的 "manifest.json" 文件后，单击 "App 原生插件配置" 中的"选择本地插件"或"选择云端插件"。

4.2 在弹出的选择框中，选择 "ZegoExpress 音视频 SDK" 后，单击"确认"，即添加成功。

5.自定义调试基座

制作自定义调试基座

5.1 选择"运行 > 运行到手机或模拟器 > 制作自定义调试基座"菜单。

5.2 在弹出的界面中，按照 uni-app 教程，填写相关信息，并单击"打包"进行云打包。

打包成功后，控制台会收到 uni-app 的相关提示。

6.切换运行基座为自定义调试基座

自定义调试基座选择"运行 > 运行到手机或模拟器 > 运行基座选择 > 自定义调试基座"菜单。

7.集成 JS 封装层

7.1 导入 JS 封装层。

在插件市场的 ZegoExpressEngine 音视频插件（JS）界面，单击右侧的"使用 HBuilderX 导入插件"。

导入的 JS 封装层将存储在 uni_modules 目录中，目录结构如下。

7.2 导入后，可以在业务代码中引入 JS 封装层，并调用 Express 相关接口，示例如下：

复制代码

import ZegoExpressEngine from '@/uni_modules/zego-ZegoExpressUniApp-JS/components/zego-ZegoExpressUniApp-JS/lib/ZegoExpressEngine';

8.设置权限

根据实际应用需要，设置应用所需权限。

进入 manifest.json 文件，打开 App 权限设置，在 App 云打包权限配置里添加权限。

复制代码

<!-- SDK 必须使用的权限 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<!-- App 需要使用的部分权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true" />

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

注意

由于 Android 6.0 在一些比较重要的权限上要求必须申请动态权限。因此还需要参考执行如下代码，permission.js 文件可以在示例代码中查看。

复制代码

import permision from "@/pages/permission.js";

if (uni.getSystemInfoSync().platform === "android") {
    await permision.requestAndroidPermission(
	"android.permission.RECORD_AUDIO"
    );
    await permision.requestAndroidPermission(
	"android.permission.CAMERA"
    );
}

（二）实现视频通话

1.功能简介

下文将介绍如何快速实现一个简单的实时音视频通话。

2.前提条件

在实现基本的实时音视频功能之前，请确保：

已在项目中集成 ZEGO Express SDK，实现基本的实时音视频功能，详情请参考快速开始 - 集成。
已在 ZEGO 控制台创建项目，并申请有效的 AppID 和 AppSign，详情请参考"控制台 - 项目管理"中的"项目信息"。

注意：SDK 同时也支持 Token 鉴权，若您对项目安全性有更高要求，建议您升级鉴权方式，详情请参考如何从 AppSign 鉴权升级为 Token 鉴权。

3.使用步骤

用户通过 ZEGO Express SDK 进行视频通话的基本流程为：

用户 A、B 加入房间，用户 B 预览并将音视频流推送到 ZEGO 云服务（推流），用户 A 收到用户 B 推送音视频流的通知之后，在通知中播放用户 B 的音视频流（拉流）。

整个推拉流过程的 API 调用时序如下图：

4.创建引擎

4.1. （可选）创建界面**

在创建引擎之前，ZEGO 推荐开发者添加以下界面元素，方便实现基本的实时音视频功能。

本地预览窗口
远端视频窗口
结束按钮

4.2. 创建引擎

调用 createEngineWithProfile 接口，将申请到的 AppID 和 AppSign 传入参数 "appID" 和 "appSign"，创建引擎单例对象。

复制代码

// 导入 ZEGO Express SDK
import ZegoExpressEngine from "@/uni_modules/zego-ZegoExpressUniApp-JS/components/zego-ZegoExpressUniApp-JS/lib/ZegoExpressEngine";

// 采用通用场景
const profile = {
appID : xxx,
// AppSign 仅满足简单的鉴权需求，如果需要升级为更加安全的鉴权方式，请参考[如何从 AppSign 鉴权升级为 Token 鉴权](https://doc-zh.zego.im/faq/token_upgrade?product=ExpressVideo&platform=all)
// AppSign 可通过[控制台](https://console.zego.im/dashboard)获取，格式为 @"39011cbxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
appSign: '39011cbxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
scenario : 0
};

ZegoExpressEngine.createEngineWithProfile(profile)

4.3.设置回调

创建引擎后开发者可根据实际需要，调用引擎实例的 on 方法设置回调。

5.登录房间

5.1 登录

您可以调用 loginRoom 接口登录房间。如果房间不存在，调用该接口时会创建并登录此房间。

roomID 和 user 的参数由您本地生成，但是需要满足以下条件:
- 同一个 AppID 内，需保证 "roomID" 全局唯一。
- 同一个 AppID 内，需保证 "userID" 全局唯一，建议开发者将 "userID" 与自己业务的账号系统进行关联。
  
  let roomConfig = {};
  // 只有传入 "isUserStatusNotify" 参数取值为 "true" 的 ZegoRoomConfig，才能收到 onRoomUserUpdate 回调。
  roomConfig.isUserStatusNotify = true;
  // 获取token传入
  roomConfig.token = "********";
  // 登录房间
  // 开始登录房间
  ZegoExpressEngine.instance().loginRoom('room1', {'userID': 'id1', 'userName': 'user1'}, roomConfig);

5.2 监听登录房间后的事件回调

可根据实际应用需要，在登录房间后监听想要关注的事件通知，比如房间状态更新、用户状态更新、流状态更新等。

roomStateUpdate：房间状态更新回调，登录房间后，当房间连接状态发生变更（如出现房间断开，登录认证失败等情况），SDK 会通过该回调通知。

roomUserUpdate：用户状态更新回调，登录房间后，当房间内有用户新增或删除时，SDK 会通过该回调通知。

只有调用 loginRoom 接口登录房间时传入 ZegoRoomConfig 配置，且 "isUserStatusNotify" 参数取值为 "true" 时，用户才能收到 roomUserUpdate 回调。

roomStreamUpdate：流状态更新回调，登录房间后，当房间内有用户新推送或删除音视频流时，SDK 会通过该回调通知。

复制代码

// 以下为常用的房间相关回调

ZegoExpressEngine.instance().on('roomStateUpdate', (roomID, state, errorCode, extendedData) => {
  // 房间状态更新回调，登录房间后，当房间连接状态发生变更（如出现房间断开，登录认证失败等情况），SDK会通过该回调通知
}); ;

ZegoExpressEngine.instance().on('roomUserUpdate', (roomID, updateType, userList) => {
  // 用户状态更新，登录房间后，当房间内有用户新增或删除时，SDK会通过该回调通知
});

ZegoExpressEngine.instance().on('roomStreamUpdate', (roomID, updateType, streamList) => {
  // 流状态更新，登录房间后，当房间内有用户新推送或删除音视频流时，SDK会通过该回调通知
});

6.推流

6.1 开始推流

调用 startPublishingStream 接口，传入流 ID 参数 "streamID"，向远端用户发送本端的音视频流。

复制代码

await ZegoExpressEngine.instance().startPublishingStream("streamID");

7.拉流

7.1 开始拉流

调用 startPlayingStream 接口，根据传入的流 ID 参数 "streamID"，拉取远端推送的音视频流。

关于远端视频流视图：

在 uni-app 的 App 环境中，若 startPlayingStream 调用成功，则无返回值，可使用
标签设置远端视频流视图。
在 uni-app 的 Web 环境中，若startPlayingStream 调用成功，会返回一个 MediaStream
对象，开发者可以用返回的 MediaStream赋值给 video 元素的 srcObject 属性设置远端视频流视图。

html 复制代码

<template>
    <!-- #ifdef APP-PLUS -->
    <zego-remote-view :streamID="playStreamID" style="height: 403.84rpx;flex: 1"></zego-remote-view>
    <!-- #endif -->
    <!-- #ifdef H5 -->
    <video id="remote_video" style="height: 403.84rpx;flex: 1;"  autoplay playsinline :muted="true"></video>
    <!-- #endif -->
</template>

8. 监听拉流后的事件回调

根据实际应用需要，在拉流后监听想要关注的事件通知，比如拉流状态更新等。

playerStateUpdate：拉流状态更新回调，调用拉流接口成功后，当拉流状态发生变更，如出现网络中断导致推流异常等情况，SDK 在重试拉流的同时，会通过该回调通知。

html 复制代码

ZegoExpressEngine.instance().on("playerStateUpdate", (streamID, state, errorCode, extendedData) => {
    /** 调用拉流接口成功后，当拉流器状态发生变更，如出现网络中断导致推流异常等情况，SDK在重试拉流的同时，会通过该回调通知 */
    //....
});

9.在线测试推拉流功能

在真机中运行项目，运行成功后，可以看到本端视频画面。

10.停止推拉流

10.1 停止推流/预览

调用 stopPublishingStream 接口停止发送本地的音视频流，结束通话。

html 复制代码

/** 停止推流 */
ZegoExpressEngine.instance().stopPublishingStream();

如果启用了本地预览，开发者可以在停止推流后根据业务需要调用 stopPreview 接口停止预览。

html 复制代码

/** 停止本地预览 */
ZegoExpressEngine.instance().stopPreview();

10.2 停止拉流

调用 stopPlayingStream 接口，停止拉取远端的音视频流。

html 复制代码

/** 停止拉流 */
ZegoExpressEngine.instance().stopPlayingStream("streamID");

10.3 退出房间

调用 logoutRoom 接口退出房间，本端会收到 roomStateUpdate 回调通知调用结果，并停止其所有推拉流以及本地预览。

html 复制代码

/** 退出房间 */
ZegoExpressEngine.instance().logoutRoom('room1');

销毁引擎

调用 destroyEngine 接口销毁引擎，用于释放 SDK 使用的资源。

html 复制代码

/** 销毁引擎 */
ZegoExpressEngine.destroyEngine();

（三）场景化音视频配置

调用方式

在创建引擎的 profile (ZegoEngineProfile) 参数中的 scenario (ZegoScenario) 字段需要指定一个场景，您可以根据实际音视频业务场景来选择。

注意：同一个房间内的用户，建议使用同一种房间场景，以获得最佳效果。

总结

通过本文的完整教程，我们从前期环境配置、SDK 集成（含本地插件导入、自定义调试基座制作、JS 封装层引入等关键操作），到核心功能实现（创建引擎、登录房间、推流拉流、实时回调监听），再到停止推拉流、退出房间、销毁引擎，已完整走完 uni-app 跨端音视频通话的技术闭环，覆盖 iOS、Android、H5 等多端场景的适配要点。

在此基础上，还可基于业务场景进一步扩展进阶能力，例如 AI 美颜、虚拟背景、屏幕共享、通话录制等。若需获取更详细的 API 说明、场景化解决方案或问题排查指南，进阶秘籍可前往即构官网文档中心查阅，也可通过官方技术支持获取针对性指导，助力各类跨端音视频产品快速落地。

【了解更多】

获取本文的Demo、开发文档、技术支持。
注册即构ZEGO开发者帐号，快速开始。