更新记录

1.2.1（2026-08-24）

更新了使用说明

1.2.0（2026-08-24）

更新了安卓、IOS、小程序支持

更新日志

平台兼容性

uni-app(4.62)

uni-app x(5.24)

wei-trtc 插件使用说明

跨平台 TRTC 实时音视频 UTS 插件，封装腾讯官方 LiteAVSDK，提供直播推流、拉流观看、连麦互动等能力。支持鸿蒙 / 安卓 / iOS / 微信小程序四端。

一、环境要求

各平台实现方式：

App 三端（鸿蒙/安卓/iOS）函数 API 完全一致，业务代码一份即可，仅视频渲染组件标签不同；小程序端因平台机制不同，使用 live-pusher/live-player 组件 + trtc-wx.js（见「小程序使用」章节）。

鸿蒙真机运行配置（必做）

首次在鸿蒙真机运行前，需完成以下两项配置：

1. 包名（bundleName）：在项目 manifest.json 的 app-harmony.distribute.bundleName 中填写你自己的应用包名（形如 com.xxx.yyy，需全局唯一，勿直接使用示例工程的 com.wei.trtcsample）。
2. 证书签名：首次运行到鸿蒙真机时，HBuilderX 会提示配置调试证书——按提示在 DevEco Studio 中生成调试签名证书（.p7b / .cer / .p12），或在 HBuilderX「运行 → 运行到手机或模拟器」的鸿蒙运行设置中完成证书配置后自动写入 manifest.json。

正式发布时，还需在 AppGallery Connect 中创建应用、配置发布证书，并以正式包名 + 证书打包。

二、系统权限

鸿蒙端

插件已在 utssdk/app-harmony/module.json5 中声明以下鸿蒙权限，编译时自动合入应用，无需使用者额外配置：

安卓端

插件已在 utssdk/app-android/AndroidManifest.xml 中声明以下安卓权限，云打包时自动合入应用，无需使用者额外配置：

iOS 端

iOS 端摄像头/麦克风权限由系统在首次调用时自动弹出授权，无需额外声明。如需自定义隐私描述文案，可在项目 manifest.json 的 app-plus.ios.privacyDescription 中配置 NSCameraUsageDescription（摄像头）与 NSMicrophoneUsageDescription（麦克风）。

注意：摄像头、麦克风为敏感权限，除上述静态声明外，App 端（鸿蒙/安卓/iOS）运行时仍需调用 requestTrtcPermissions 动态申请，否则无法采集音视频。

三、导入插件

方式一：插件市场导入（推荐）

HBuilderX 中右键项目 uni_modules 目录 → 从插件市场导入 → 搜索 wei-trtc。

方式二：手动导入

将插件目录复制到项目的 uni_modules/wei-trtc 下即可，无需额外配置。

安卓端自定义基座（必做）

安卓端插件依赖三方库 com.tencent.liteav:LiteAVSDK_Professional（maven），标准基座不包含该依赖。运行到安卓真机时如提示：

uni_module [wei-trtc] (Android) 存在三方依赖或资源引用，请到 HBuilderX【设置-运行配置】配置运行环境或者提交云端打自定义基座。

需按以下任一方式处理（详见官网 Android UTS 扩展开发）：

• 方式一（推荐）：云端打自定义基座 — HBuilderX「运行 → 运行到手机或模拟器 → 制作自定义调试基座」，云端打包时自动拉取 maven 依赖；下载并安装自定义基座后，再运行到该设备。
• 方式二：本地 Gradle 环境 — 「设置 → 运行配置」中配置 Gradle（≥7.5 且 <9.0）、Gradle JDK（JDK 17）、Android SDK（build-tools ≥30.0.0、platforms ≥ android-30）；首次运行会自动安装「uts 开发扩展 - Android」插件，之后可本地直接真机运行。

四、获取 userSig（云函数 / 自有后端 二选一）

进房签名 userSig 需要用腾讯云 secretKey 计算。若把密钥打包在客户端，容易被反编译破解导致流量被盗用，因此密钥必须放在服务端。插件不强制依赖 uniCloud，以下两种方式任选其一：

密钥与费用归属（务必理解）：

• SDKAppId / SecretKey 必须由每个使用者填写自己的，在腾讯云实时音视频控制台用各自账号创建应用获取
• TRTC 按用量计费（音视频时长/分辨率/人数），费用绑定在 SDKAppId 对应的腾讯云账号上。插件不内置任何作者的密钥，每位使用者用自己账号的密钥，费用各自承担，互不扣费、互不串数据

方式一：使用 uniCloud 云函数（推荐，最省事）

云函数路径： uni_modules/wei-trtc/uniCloud/cloudfunctions/wei-trtc-usersig/index.js

部署步骤：

1. 用你自己的腾讯云账号在实时音视频控制台创建应用，记下 SDKAppId 和密钥
2. 在 HBuilderX 中为项目关联 uniCloud 服务空间（阿里云或腾讯云均可）
3. 右键 uniCloud/cloudfunctions/wei-trtc-usersig → 上传部署
4. 右键该云函数 → 配置云函数环境变量（HBuilderX 5.08+，或登录 uniCloud 控制台在「云函数/云对象」里配置），新增两个变量：
   • TRTC_SDKAPPID = 你的 SDKAppId（纯数字）
   • TRTC_SECRETKEY = 你的密钥
5. 客户端调用（返回 { code: 0, sdkAppId, userId, userSig, expire }）：

// #ifdef APP-HARMONY
uniCloud.callFunction({
    name: 'wei-trtc-usersig',
    data: { userId: 'user_001' }
}).then((res) => {
    const r = res.result || {};
    if (r.code === 0 && r.userSig) {
        // 用 r.sdkAppId / r.userSig 调用 enterRoom
    }
});
// #endif

加密说明：插件已在 package.json 的 uni_modules.encrypt 中声明该云函数加密，使用者无法查看云函数源码；但密钥通过环境变量配置、与源码分离，因此加密不影响每个使用者填自己的密钥。

方式二：自有后端生成（不依赖 uniCloud）

如果你的项目不用 uniCloud，userSig 只是 enterRoom 的一个入参，从哪里获取完全由你决定——用自己的后端服务器计算即可。

可选清理： 删除插件目录 uni_modules/wei-trtc/uniCloud/，并删掉 package.json 中 uni_modules.encrypt 那一项（保持整洁，不影响插件功能）。

后端实现： 任意语言（Node/Java/PHP/Python/Go/.NET）腾讯云都提供了官方 userSig 生成示例，参考：UserSig 服务端生成方案。

前端调用： 调你自己的后端接口拿到 userSig 后直接进房：

// #ifdef APP-HARMONY
// 你的业务后端接口（任意语言实现），返回 { sdkAppId, userSig }
const res = await myBackend.getUserSig(this.userId);
enterRoom({
    sdkAppId: Number(res.sdkAppId),
    userId: this.userId,
    userSig: res.userSig,
    roomId: 868,
    role: 20,
    scene: 'live'
});
// #endif

五、快速上手

以下为完整接入流程代码（可直接复制到鸿蒙端 .vue 页面）：

<template>
    <view>
        <!-- 视频渲染组件：viewid 必须与 startLocalPreview / startRemoteView 传入的 viewId 完全一致 -->
        <embed tag="trtcvideoview" :options="{ viewid: 'trtcMainView' }"
            style="width: 100vw; height: 100vh;"></embed>
    </view>
</template>

<script>
    // 仅在鸿蒙平台加载插件，其他平台走空实现保证编译通过
    // #ifdef APP-HARMONY
    import {
        createTrtcInstance,
        destroyTrtcInstance,
        requestTrtcPermissions,
        enterRoom,
        exitRoom,
        startLocalPreview,
        stopLocalPreview,
        startLocalAudio,
        stopLocalAudio,
        switchCamera,
        muteLocalAudio,
        switchRole,
        setBeautyStyle,
        startRemoteView,
        stopRemoteView,
        onTrtcEvent,
        offTrtcEvent,
        TRTC_ROLE_ANCHOR,      // 20 主播
        TRTC_AUDIO_QUALITY_DEFAULT,
        TRTC_STREAM_TYPE_BIG   // 0 主流（摄像头）
    } from '@/uni_modules/wei-trtc';
    // #endif

    // scene 字符串常量在 JS 层本地定义（UTS 插件不导出字符串常量，避免引号丢失）
    const TRTC_SCENE_LIVE = 'live';
    const TRTC_SCENE_VIDEOCALL = 'videocall';

    export default {
        data() {
            return {
                isFront: true // 前置摄像头
            }
        },
        onReady() {
            this.initTrtc();
        },
        onUnload() {
            // 页面卸载时务必退出房间并销毁实例，释放原生资源
            // #ifdef APP-HARMONY
            stopLocalPreview();
            stopLocalAudio();
            exitRoom();
            destroyTrtcInstance();
            // #endif
        },
        methods: {
            initTrtc() {
                // #ifdef APP-HARMONY
                // 1. 动态申请麦克风 + 摄像头权限（推流前必须申请）
                requestTrtcPermissions((granted) => {
                    if (!granted) {
                        uni.showToast({ title: '需要摄像头和麦克风权限', icon: 'none' });
                        return;
                    }
                    // 2. 创建 TRTC 实例（幂等，可重复调用）
                    createTrtcInstance();
                    // 3. 订阅事件（进房结果等均通过事件回调）
                    this.bindEvents();
                    // 4. 进房（userSig 请由您的业务后端下发）
                    enterRoom({
                        sdkAppId: 1400000000,          // 腾讯云 sdkAppId
                        userId: 'user_001',             // 用户唯一标识
                        userSig: 'xxx',                 // 登录签名，由服务端下发
                        roomId: 868,                    // 房间号（数字）
                        role: TRTC_ROLE_ANCHOR,         // 20 主播可推流，21 观众仅观看
                        scene: TRTC_SCENE_LIVE          // live 直播 / videocall 视频通话
                    });
                });
                // #endif
            },
            bindEvents() {
                // #ifdef APP-HARMONY
                // 进房结果：result > 0 成功（耗时ms），result < 0 失败（错误码）
                onTrtcEvent('onEnterRoom', (res) => {
                    if (res['result'] > 0) {
                        // 主播：进房成功后开启本地预览 + 音频上行
                        // viewid 'trtcMainView' 与模板中 embed 的 viewid 一致
                        startLocalPreview(this.isFront, 'trtcMainView');
                        startLocalAudio(TRTC_AUDIO_QUALITY_DEFAULT);
                    }
                });
                // 远端用户开启摄像头：订阅渲染其画面
                onTrtcEvent('onUserVideoAvailable', (res) => {
                    if (res['available']) {
                        // 观众看主播：订阅到主画面；streamType 0=主流（摄像头）
                        startRemoteView(res['userId'], TRTC_STREAM_TYPE_BIG, 'trtcMainView');
                    } else {
                        stopRemoteView(res['userId'], TRTC_STREAM_TYPE_BIG);
                    }
                });
                // 错误回调
                onTrtcEvent('onError', (res) => {
                    console.error('TRTC 错误', res['errCode'], res['errMsg']);
                });
                // #endif
            }
        }
    }
</script>

六、视频渲染说明

各端视频渲染组件不同（App 三端函数 API 完全一致，仅渲染组件标签不同）：

• 鸿蒙（APP-HARMONY）：<embed tag="trtcvideoview" :options="{ viewid: 'xxx' }">
• 安卓 / iOS（APP-ANDROID / APP-IOS）：<wei-trtc-video-view viewid="xxx">
• 微信小程序（MP-WEIXIN）：uni-app 内置 <live-pusher> / <live-player>

注意：

• 每个渲染位通过 viewid（鸿蒙 embed 为 options.viewid）区分，必须与 startLocalPreview(frontCamera, viewId) / startRemoteView(userId, streamType, viewId) 传入的 viewId 完全一致，否则画面不显示
• 渲染组件需显式设置宽高（如 style="width:100vw;height:100vh"），否则可能无法显示
• <embed> 的 tag 与 <wei-trtc-video-view> 标签名必须全小写

七、API 参考

实例与权限

房间

TrtcEnterRoomParams 参数：

本地音视频（推流）

美颜与镜像

远端视频（拉流）

自定义消息

事件订阅

支持的事件列表：

常量

八、典型场景流程

主播推流： requestTrtcPermissions → createTrtcInstance → onTrtcEvent 绑事件 → enterRoom(role=20) → 收到 onEnterRoom(result>0) → startLocalPreview + startLocalAudio

观众拉流观看： createTrtcInstance → 绑事件 → enterRoom(role=21) → 收到 onUserVideoAvailable(available=true) → startRemoteView(userId, 0, viewId)

观众连麦（上麦）： switchRole(20) → startLocalPreview(frontCamera, 小窗viewId) → startLocalAudio；下麦时反向操作后 switchRole(21)

退出房间： stopLocalPreview → stopLocalAudio → exitRoom → 收到 onExitRoom 后 offTrtcEvent 清理订阅 → destroyTrtcInstance

九、注意事项

1. userSig 安全：正式环境务必由服务端计算下发 userSig，切勿将密钥打包进客户端。推荐直接使用插件内置的加密云函数 wei-trtc-usersig（见「三、userSig 云端生成」），密钥保留在云端不泄露；示例工程中的本地生成方式仅用于 Demo 快速调通。参考：腾讯云 UserSig 服务端生成方案
2. viewid 一致性：embed 的 viewid 与 startLocalPreview/startRemoteView 传入的 viewId 必须完全一致
3. 进房结果异步：enterRoom 无返回值，成功/失败均通过 onEnterRoom 事件回调判断
4. 资源释放：页面卸载（onUnload）时务必执行退房 + destroyTrtcInstance()，否则摄像头/麦克风被占用导致下次进入失败
5. 模拟器不支持：TRTC SDK（鸿蒙/安卓/iOS）均不支持模拟器，请始终使用真机调试
6. 权限：插件已声明各端所需权限（摄像头、麦克风、网络等），但 App 端运行时仍需调用 requestTrtcPermissions 动态申请麦克风与摄像头权限
7. 条件编译：各端实现不同（App 走 UTS 函数 API、小程序走 live-pusher 组件），页面调用处建议用 #ifdef APP-HARMONY / APP-ANDROID / APP-IOS / MP-WEIXIN 条件编译区分

十、小程序使用（微信）

前置：小程序音视频资质申请（必做）

微信小程序的 live-pusher / live-player 组件属特殊能力，出于合规要求并未对所有小程序开放，使用前必须完成以下步骤：

1. 非个人主体认证：小程序必须是企业/组织/政府等非个人主体认证的账号，个人小程序无法使用 live-pusher / live-player。
2. 服务类目审核：小程序所选「服务类目」必须在微信开放的范围内。支持音视频直播/通话的主要类目包括：社交 - 直播、教育 - 在线视频课程、医疗 - 互联网医院、IT科技 - 多方通信、工具 - 视频客服、政府主体账号、房地产服务 - 房地产营销 等（完整类目及资质要求以微信官方「服务类目说明」为准）。在「设置 → 基本设置 → 服务类目」中选择符合实际业务场景的类目并提交审核。
3. 接口权限开通：类目审核通过后，在小程序管理后台「开发 → 开发管理 → 接口设置」中自助开通「实时播放音视频流」与「实时录制音视频流」两个接口权限。
4. 服务器域名配置：将 TRTC 服务商相关域名添加到小程序后台「开发 → 开发设置 → 服务器域名」的 request 合法域名（如需还需配置 socket 合法域名），否则真机上拉流会黑屏。

参考：微信 live-player 组件文档、腾讯云小程序类目资质要求。

微信小程序端 TRTC 与 App 端机制不同，使用 uni-app 内置的 <live-pusher>（推流）和 <live-player>（拉流）组件，配合插件内置的腾讯官方小程序 SDK（common/trtc-wx.js）管理进房与推拉流。

引入 SDK：

import * as TRTC from '@/uni_modules/wei-trtc/common/trtc-wx.js';

主播推流（模板 + 逻辑）：

<live-pusher
  :url="pusher.url"
  mode="RTC"
  :enable-mic="true"
  :enable-camera="true"
  @statechange="onPushStateChange"
  style="width: 100vw; height: 100vh;" />

const trtc = new TRTC();
const pusher = trtc.createPusher();
// 进房
const { sdkAppId, userSig } = await getUserSigFromBackend(); // userSig 由服务端下发
const enterRes = await trtc.enterRoom({
  sdkAppID: sdkAppId,
  userID: this.userId,
  userSig: userSig,
  roomID: this.roomId,
  scene: 'live',
  enableMic: true,
  enableCamera: true
});
this.pusher = enterRes.pusher;
trtc.getPusherInstance().start(); // 开始推流

观众拉流：

<live-player
  v-for="player in playerList"
  :src="player.url"
  mode="RTC"
  style="width: 100vw; height: 100vh;" />

// 监听远端视频流，创建 player 实例
trtc.on(trtc.EVENT.REMOTE_VIDEO_ADD, (event) => {
  const player = trtc.createPlayer({ streamUrl: event.stream.streamUrl });
  this.playerList.push(player);
});

说明：小程序端 userSig 同样建议由服务端下发（可复用插件内置的 uniCloud 云函数 wei-trtc-usersig，小程序端也能调用 uniCloud.callFunction）。trtc-wx.js 为腾讯官方小程序 TRTC SDK，事件模型与 App 端不同，详见腾讯官方文档。

十一、完整示例

配套示例工程见 WEI-TRTCCloud-sample：

• 入口页 pages/index/index.vue：APP/小程序/鸿蒙平台展示「直播（主播推流）/ 直播（观众拉流）」入口
• 演示页 pages/harmonylive/harmonylive.vue：覆盖进房/退房、推流、拉流、连麦、切换摄像头、静音、美颜、自定义消息、事件日志全部能力，并提供「云函数 / 本地生成」两种 userSig 获取方式切换
• 云端 userSig 云函数：uni_modules/wei-trtc/uniCloud/cloudfunctions/wei-trtc-usersig/
• 测试 userSig 本地生成工具：js_sdk/trtc/gen-test-usersig.js（密钥配置在 common/app.js，仅供本地快速调通）

两台鸿蒙真机分别以主播/观众进入同一房间号即可联调测试。