uniapp直播插件集成教程：20分钟快速接入企业级直播能力

在跨端开发的浪潮中，uniapp 已经成为很多企业的首选框架。但在集成直播功能时，很多开发者会遇到同一个问题：直播功能怎么在 uniapp 里实现？插件怎么安装？推流和拉流怎么配置？

这篇文章从零开始，完整演示 uniapp 直播插件的集成全流程。你可以直接复制代码到自己的项目中使用。

一、直播集成方案选择：插件 vs SDK

在 uniapp 中集成直播能力，主要有两种方式：

对于大多数团队，插件方式性价比最高。如果后续需要扩展功能，再逐步叠加原生能力即可。

二、插件安装与项目配置

2.1 通过HBuilderX安装

打开 HBuilderX → 菜单栏「插件」→ 选择项目中需要使用 uniapp 插件的模块 → 搜索「直播插件」→ 点击「安装到项目」。

2.2 manifest.json配置

安装完成后，在 manifest.json 中配置直播相关权限：

{
  "app-plus": {
    "distribute": {
      "plugins": {
        "live-pusher": {
          "version": "1.0.0"
        },
        "live-player": {
          "version": "1.0.0"
        }
      }
    }
  }
}

2.3 权限声明

在 pages.json 中添加需要直播的页面：

{
  "pages": [
    {
      "path": "pages/live/push",
      "style": {
        "navigationBarTitleText": "直播推流",
        "app-plus": {
          "titleNView": false,
          "scrollIndicator": "none"
        }
      }
    }
  ]
}

三、App端推流核心代码

推流（推送本地音视频到服务器）是直播最核心的能力。以下是完整的推流代码：

3.1 推流页面模板

<template>
    <view class="live-container">
        <live-pusher
            id="livePusher"
            class="pusher"
            :url="pushUrl"
            mode="RTC"
            :autopush="true"
            :muted="false"
            :enable-camera="true"
            :zoom="false"
            :beauty="beauty"
            @statechange="onStateChange"
            @netstatus="onNetStatus"
            @error="onError"
        />
        <view class="control-bar">
            <button @click="toggleCamera">切换摄像头</button>
            <button @click="toggleMic">{{ micOn ? '静音' : '开麦' }}</button>
            <button @click="stopPush" class="btn-stop">结束直播</button>
        </view>
    </view>
</template>

<script>
export default {
    data() {
        return {
            pushUrl: '',
            pusherContext: null,
            beauty: {
                style: 'smooth',    // 美颜风格
                whiten: 0.3,        // 美白 0-1
                smooth: 0.5,        // 磨皮 0-1
            },
            micOn: true,
            cameraOn: true,
        }
    },
    onReady() {
        // 获取推流组件上下文
        this.pusherContext = uni.createLivePusherContext('livePusher', this);
        // 初始化推流地址
        this.initPushUrl();
    },
    methods: {
        initPushUrl() {
            // 从后端获取推流地址
            // 实际项目中通过接口获取，这里示意
            uni.request({
                url: 'https://api.videotvai.com/api/v1/live/push-url',
                method: 'POST',
                data: {
                    roomId: 'room_123456',
                    userId: 'user_' + Date.now()
                },
                success: (res) => {
                    this.pushUrl = res.data.pushUrl;
                }
            });
        },
        onStateChange(e) {
            console.log('推流状态:', e.detail.code, e.detail.message);
            // code=200 表示推流成功
        },
        onNetStatus(e) {
            // 网络状态监控
            const status = e.detail.info;
            if (status.videoQPS < 500) {
                console.warn('推流质量下降，建议检查网络');
            }
        },
        onError(e) {
            console.error('推流错误:', e.detail.errCode, e.detail.errMsg);
            uni.showToast({ title: '推流异常：' + e.detail.errMsg, icon: 'none' });
        },
        toggleCamera() {
            this.pusherContext.switchCamera();
        },
        toggleMic() {
            this.micOn = !this.micOn;
            this.pusherContext.setMicEnabled({ enable: this.micOn });
        },
        stopPush() {
            this.pusherContext.stop();
            uni.navigateBack();
        }
    }
}
</script>

3.2 推流地址生成（后端接口参考）

推流地址不应由前端直接拼接，必须由后端生成以保障安全：

// Node.js 后端示例
function generatePushUrl(roomId, userId) {
    const domain = 'push.videotvai.com';
    const streamKey = `${roomId}_${userId}_${Date.now()}`;
    // 签名验证
    const sign = crypto
        .createHmac('sha256', SECRET_KEY)
        .update(streamKey)
        .digest('hex')
        .substring(0, 16);

    return `rtmp://${domain}/live/${streamKey}?sign=${sign}`;
}

四、App端拉流播放

拉流（播放端接收直播流）和推流对应。以下是一个完整的播放器页面：

<template>
    <view class="player-container">
        <live-player
            id="livePlayer"
            class="player"
            :src="playUrl"
            mode="RTC"
            :autoplay="true"
            :muted="false"
            :enable-camera="false"
            object-fit="fillCrop"
            @statechange="onPlayState"
            @error="onPlayError"
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            playUrl: '',
            playerContext: null,
        }
    },
    onLoad(options) {
        // 从上一页传入房间ID
        this.playUrl = options.playUrl || '';
    },
    onReady() {
        this.playerContext = uni.createLivePlayerContext('livePlayer', this);
    },
    methods: {
        onPlayState(e) {
            if (e.detail.code === 200) {
                console.log('播放成功');
            }
        },
        onPlayError(e) {
            console.error('播放错误:', e.detail.errMsg);
        }
    }
}
</script>

五、H5端直播集成（WebRTC）

uniapp 的 H5 端通过 WebRTC 实现直播能力。H5端的特点是即时可用、无需安装，但要依赖浏览器的 WebRTC 支持。

5.1 H5推流

// H5端通过 WebRTC 推流
async function startH5Push() {
    try {
        const stream = await navigator.mediaDevices.getUserMedia({
            video: { width: 720, height: 1280 },
            audio: true
        });

        // 获取视频轨道并发送到信令服务器
        const videoTrack = stream.getVideoTracks()[0];
        const audioTrack = stream.getAudioTracks()[0];

        // 通过 WebSocket 连接信令服务器
        const ws = new WebSocket('wss://signal.videotvai.com/ws');

        ws.onopen = () => {
            // 发送 SDP Offer
            const pc = new RTCPeerConnection();
            pc.addTrack(videoTrack);
            pc.addTrack(audioTrack);

            pc.createOffer().then(offer => {
                pc.setLocalDescription(offer);
                ws.send(JSON.stringify({
                    type: 'offer',
                    sdp: offer.sdp,
                    roomId: 'room_123456'
                }));
            });
        };

        ws.onmessage = (event) => {
            const msg = JSON.parse(event.data);
            if (msg.type === 'answer') {
                pc.setRemoteDescription(new RTCSessionDescription({
                    type: 'answer',
                    sdp: msg.sdp
                }));
            }
        };
    } catch (err) {
        console.error('H5推流启动失败:', err);
    }
}

5.2 H5拉流

// H5端播放
async function startH5Play(playUrl) {
    // 使用 flv.js 播放
    const flvjs = require('flv.js');

    if (flvjs.isSupported()) {
        const videoElement = document.getElementById('player');
        const flvPlayer = flvjs.createPlayer({
            type: 'flv',
            url: playUrl,
        });
        flvPlayer.attachMediaElement(videoElement);
        flvPlayer.load();
        flvPlayer.play();
    }
}

六、小程序端直播配置

uniapp 编译到微信小程序时，需要使用小程序的 live-pusher 和 live-player 组件。

6.1 小程序直播资质

在小程序后台 → 「功能」→ 「直播」→ 申请开通直播能力。需要满足：

• 已完成企业认证的小程序
• 小程序类目在微信允许的准入范围内
• 近半年无严重违规

6.2 小程序推流代码

<!-- pages/live/push.wxml -->
<live-pusher
    id="pusher"
    url="{{pushUrl}}"
    mode="RTC"
    autopush="{{true}}"
    bindstatechange="onStateChange"
    binderror="onError"
    style="width:100%;height:100vh;"
/>

6.3 uniapp条件编译

如果你的项目同时支持多端，可以使用条件编译区分平台代码：

<template>
    <view>
        <!-- #ifdef APP-PLUS -->
        <live-pusher ... />
        <!-- #endif -->

        <!-- #ifdef MP-WEIXIN -->
        <live-pusher ... />
        <!-- #endif -->

        <!-- #ifdef H5 -->
        <video id="web-player" />
        <!-- #endif -->
    </view>
</template>

七、常见问题与优化

问题1：推流黑屏/无画面

排查步骤：1) 检查摄像头权限是否已开启；2) 确保 live-pusher 组件的 enable-camera 为 true；3) 推流地址是否有效；4) Android端需要申请 CAMERA 和 RECORD_AUDIO 权限。

问题2：推流延迟过高（>3秒）

原因和解决方案：1) 网络上行带宽不足 → 降低推流分辨率到 540P；2) 使用了标准直播模式 → 切换为 RTC 模式（低延迟）；3) CDN节点距离远 → 配置就近接入节点；4) 播放端使用了 HLS 协议 → 改用 FLV 或 WebRTC 拉流。

问题3：uniapp编译到iOS崩溃

iOS端使用直播功能需要在 Info.plist 中添加 NSCameraUsageDescription 和 NSMicrophoneUsageDescription 权限说明。HBuilderX 打包时需要在「iOS 隐私信息访问许可描述」中填写。

问题4：推流成功后播放端看不到画面

检查：1) 推流端的推流地址和播放端的播放地址对应的流ID是否一致；2) 推流端的音频/视频是否成功发送到服务器；3) 检查推流日志是否有 error 事件；4) 可以通过推流工具的预览功能验证。

相关阅读

• 《企业级直播SDK集成完全指南》 — Web/小程序/uni-app三端方案
• 《企业直播技术架构选型指南》 — 直播技术栈决策
• 《企业直播设备与基础搭建指南》 — 直播设备选型