文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>无 UI 集成>搭建视频直播>开始直播>开始直播（uni-app）

开始直播（uni-app）

最近更新时间：2025-11-12 17:54:22

我的收藏

本页目录：

本文档将帮助您使用 AtomicXCore SDK 的核心组件 LiveCoreView，快速构建一个包含主播开播和观众观看功能的基础直播 App。

核心功能

LiveCoreView 是一个专为直播场景设计的轻量级 UI 组件，是您构建直播场景的核心，它封装了所有复杂的底层直播技术（例如推拉流、连麦、音视频渲染）。您可以将 LiveCoreView 作为直播画面的“画布”，专注于上层 UI 与交互的开发。
通过下方的视图层级示意图，您可以直观了解 LiveCoreView 在直播界面中的位置和作用：


准备工作

步骤1：开通服务

请参见 开通服务，获取体验版或付费版 SDK。

步骤2：在当前项目中导入 AtomicXCore

1. 安装组件：打开 AtomicXCore SDK ，单击下载插件并导入HBuilderX，选择需要集成的项目并单击确定。

2. 配置工程权限: 请在应用的 manifest.json 文件的app-plus > distribute 节点下，确保添加了以下必要的权限：
Android 平台（android节点）：在 permissions 数组中，请确保包含以下权限：
"<uses-permission android:name=\\"android.permission.RECORD_AUDIO\\" />",
"<uses-permission android:name=\\"android.permission.CAMERA\\"/>"
iOS 平台（ios 节点）：在 privacyDescription 对象中，请确保包含以下描述：
"NSCameraUsageDescription" : "应用需要访问您的相机以进行直播",
"NSMicrophoneUsageDescription" : "应用需要访问您的麦克风以进行直播"
在 UIBackgroundModes 数组中，添加 audio 以支持后台播放音频。
"UIBackgroundModes" : [ "audio" ]

步骤3：实现登录逻辑

在您的项目中调用 LoginState 中的 login 方法完成登录，这是使用 AtomicXCore 所有功能的关键前提。
重要：
推荐在您 App 自身的用户账户登录成功后，再调用 LoginState 中的 login 方法，以确保登录业务逻辑的清晰和一致。
import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
  
const { login } = useLoginState();
  
const handleLogin = () => {
    login({
      sdkAppID: 1400000001,  // 替换为您的 SDKAppID
      userID: "test_001",    // 替换为您的 UserID
      userSig: "xxxxxxxxxx"  // 替换为您的 UserSig
    })
 }
登录接口参数说明：
参数
类型
说明
sdkAppID
number
从 控制台 获取，通常是以 140 或 160 开头的 10 位整数。
userID
string
当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，请勿使用 1、123 等简单 ID。
userSig
string
用于腾讯云鉴权的票据。请注意：
开发环境：您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。
生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参考 服务端生成 UserSig。
更多信息请参见 如何计算及使用 UserSig。

搭建基础直播间

步骤1：实现主播视频开播

主播开播流程如下，您只需执行以下几步操作，即可快速搭建主播视频直播。


1. 初始化主播推流的视图
在您的主播页中，引入 LiveCoreView 组件，将 viewType 指定为 PUSH_VIEW（推流视图）， 并且为组件绑定当前直播 ID。
<live-core-view :viewType="PUSH_VIEW" :liveID="xxx"></live-core-view>
2. 打开摄像头和麦克风
通过调用 DeviceState 的 openLocalCamera、openLocalMicrophone 接口打开摄像头和麦克风，您无需做额外操作，LiveCoreView 会自动预览当前摄像头的视频流，示例代码如下：
 import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
 import { onMounted } from 'vue';
 const { openLocalCamera, openLocalMicrophone } = useDeviceState();
 onMounted(() => {   
    openLocalMicrophone();
    openLocalCamera({ isFront: true });
  })
3. 开始直播
通过调用 LiveListState 的 createLive 接口开始视频直播，完整示例代码如下：
import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";

const { createLive } = useLiveListState();

// 开始直播
const startLive = () => {
    createLive({
      liveInfo: {
        liveID: 'xxx', // 设置直播的房间 id
        liveName: 'text', // 设置直播的房间名称
        seatLayoutTemplateID: 600, // 配置布局模板，默认：600 动态宫格布局
        keepOwnerOnSeat: true, // 配置主播始终在麦位上
      },
      success: () => {        
        console.log('创建直播间成功')
        //您可以在这里进行页面的跳转
      },
      fail: (error) => {
        console.log('创建直播间失败', error)
      }
    });
  };
LiveInfo参数说明:
参数名
类型
属性
描述
liveID
string
必填
直播间的唯一标识符
liveName
string
选填
直播间的标题
notice
string
选填
直播间的公告信息
isMessageDisable
Bool
选填
是否禁言（true：是，false：否）
isPublicVisible
Bool
选填
是否公开可见（true：是，false：否）
isSeatEnabled
Bool
选填
是否启用麦位功能（true：是，false：否）
keepOwnerOnSeat
Bool
选填
是否保持房主在麦位上
maxSeatCount
number
必填
最大麦位数量
seatMode
string
选填
上麦模式（'FREE'：自由上麦，'APPLY'：申请上麦）
seatLayoutTemplateID
number
必填
麦位布局模板 ID
coverURL
string
选填
直播间的封面图片地址
backgroundURL
string
选填
直播间的背景图片地址
categoryList
[number]
选填
直播间的分类标签列表
activityStatus
number
选填
直播活动状态
isGiftEnabled
Bool
选填
是否启用礼物功能（true：是，false：否）
4. 结束直播
直播结束后，主播可以调用 LiveListState 的 endLive 接口结束直播。SDK 会处理停止推流和销毁房间的逻辑。
import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
const { endLive } = useLiveListState();
const { closeLocalCamera, closeLocalMicrophone } = useDeviceState();

const stopLive = () => {
    endLive({
      success: () => {
        // 关闭本地设备
        closeLocalCamera();
        closeLocalMicrophone()
       },
    });
}

步骤2：实现观众进房观看

观众观看流程如下，通过简单几步操作，即可实现观众观看直播。


1. 实现观众拉流页面
在您的观众页中，引入 LiveCoreView 组件，将 viewType 指定为 PLAY_VIEW（拉流视图）， 并且为组件绑定当前直播 ID。
<live-core-view :viewType="PLAY_VIEW" :liveID="xxx"></live-core-view>
2. 进入直播间观看
通过调用 LiveListState 的 joinLive 接口加入直播，您无需做额外操作，LiveCoreView 会自动播放当前房间的视频流，完整示例代码如下：
import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";

const { joinLive } = useLiveListState();

// 加入直播
const joinLive = () => {
     joinLive({
        liveID: 'xxx' // 与主播开播同样的 liveID
        success: () => {        
          console.log('加入直播间成功')
          //您可以在这里进行页面的跳转
        },
        fail: (error) => {
          console.log('加入直播间失败', error)
        }
     })
}
3. 退出直播
观众退出直播间时，需要调用 LiveListState 的 leaveLive 接口退出直播。SDK 会自动停止拉流并退出房间。
import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";

const { leaveLive } = useLiveListState();

// 离开直播
const exitLive = () => {
     leaveLive({
        success: () => {        
          console.log('离开直播间成功')
          //您可以在这里进行页面的跳转
        },
        fail: (error) => {
          console.log('离开直播间失败', error)
        }
     })   
}

步骤3：监听直播事件

在观众加入直播间后，您还需要处理一些房间内的“被动”事件。例如，主播主动结束了直播，或者观众因为违规等原因被踢出房间。如果不监听这些事件，观众端 UI 可能会停留在黑屏页面，影响用户体验。
您可以通过订阅 LiveListState 提供的 addLiveListListener 来实现事件监听。
import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
import { onMounted } from 'vue';
const { addLiveListListener } = useLiveListState()

onMounted(() => {
    addLiveListListener('onLiveEnded', 
      { callback: (event) => {
        const res = JSON.parse(event)
        console.log("直播结束", res)
        // 在这里处理直播间结束后的相关逻辑，例如关闭当前页面
      }
    })
    addLiveListListener( 'onKickedOutOfLive',
      { callback: (event) => {
        const res = JSON.parse(event)
        console.log("被踢出房间", res.reason)
        // 可以根据被踢出房间的原因进行弹窗提示
      }
    })
})

运行效果

集成 LiveCoreView 后，您将得到一个纯净的视频渲染视图，它已具备完整的直播业务能力，但没有任何交互 UI。您可以参考下一章节 丰富直播场景 来完善直播场景。


丰富直播场景

当您完成了基础的直播功能后，您可以参考以下功能指南来为直播添加丰富的互动玩法。
直播功能
功能介绍
功能 States
实现指南
实现观众音视频连线
观众申请上麦，与主播进行实时视频互动。
实现观众连线
实现主播跨房连线
两个不同房间的主播进行连线，实现互动
实现主播连线
添加弹幕聊天功能
观众可以在直播间发送和接收实时文字消息。
实现弹幕功能
构建礼物赠送系统
观众可以向主播赠送虚拟礼物，增加互动和趣味性。
GiftState
实现礼物功能

API 文档

State
功能描述
API 文档
LiveListState
直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（如被踢出、结束）。
API 文档
DeviceState
音视频设备控制：麦克风（开关 / 音量）、摄像头（开关 / 切换 / 画质）、屏幕共享，设备状态实时监听。
API 文档
CoGuestState
观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。
API 文档
CoHostState
主播跨房连线：支持多布局模板（动态网格等），发起 / 接受 / 拒绝连线，连麦主播互动管理。
API 文档
GiftState
礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。
API 文档
BarrageState
弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。
API 文档
LikeState
点赞互动：发送点赞，监听点赞事件，同步总点赞数。
API 文档
LiveAudienceState
观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。
API 文档
AudioEffectState
音频特效：变声（童声 / 男声）、混响（KTV 等）、耳返调节，实时切换特效。
API 文档
BaseBeautyState
基础美颜：调节磨皮 / 美白 / 红润（0-100 级），重置美颜状态，同步效果参数。
API 文档

常见问题

在使用 AtomicXCore 这样的原生能力 SDK 时，开发者经常会遇到 uniapp 跨端开发本身的一些共性问题，以下是一些常见问题及其解决方案，可以帮助您规避许多常见的“坑”。

跨端兼容性问题

问题：原生组件层级最高，遮挡弹窗。
原因：像 <video>, <map>, <live-player> LiveCoreView 这类组件，是由原生渲染的，层级永远高于 WebView 渲染的普通组件。
解决方案：
使用 cover-view：uniapp 提供了 cover-view 和 cover-image，它们可以覆盖在原生组件之上，但样式支持有限。
切换到 nvue：如果页面交互复杂，需要大量元素覆盖在原生组件上，最佳实践是将整个页面用 nvue 来编写。nvue 的所有组件都是原生渲染，不存在层级问题。

nvue 与 vue 的抉择问题

问题：不知道什么时候该用 nvue，什么时候用 vue。
选型建议：
默认用vue：适合绝大多数业务和 UI 复杂的页面。
当遇到长列表滑动卡顿、复杂动画掉帧、需要覆盖原生组件等性能或层级问题时，再考虑将该页面重构为 nvue。直播、地图这类页面是 nvue 的绝佳应用场景。

原生能力集成问题

问题：插件调用失败或无响应。
解决方案：
必须打包自定义基座：在开发调试原生插件时，不能使用标准基座，必须通过 HBuilderX -> 运行 -> 运行到手机或模拟器 -> 制作自定义基座，然后选择这个自定义基座来运行。
检查权限：如本文档“准备工作”中所述，manifest.json 必须声明相机、麦克风等权限。
查看原生日志：这是终极调试手段。通过 Android Studio (Logcat) 或 Xcode (Console) 查看设备的原生日志，通常能发现最直接的错误信息。



中国站
目录