更新记录

1.0.0（2026-11-10）

• 新增轻量直播候选：系统媒体采集编码、自研RTMP、Web WHIP/HLS和微信适配。
• 新增房间、聊天、商品规格及订单意图Mock，开发者业务JSON桥与类型化适配合同。
• 新增uni-app / uni-app x示例、内置传统nvue画面组件、诊断报告与复制回退。
• 新增固定开源依赖许可、自有Harmony HAR源码及双宿主验证工具；验证范围以客户说明和项目记录为准。
• 调整为单一lizhao-live插件目录，内置画面组件复用同一媒体内核；uni-app x整文件条件编译排除nvue兼容组件，保留原生SDK与标准组件边界。

平台兼容性

uni-app(5.34)

uni-app x(5.34)

lizhao-live 轻量直播 UTS 插件

介绍

面向 uni-app 和 uni-app x 的轻量直播开发候选：自研媒体层、直播间、聊天、商品规格与订单意图。默认使用本地 Mock，管理后台和业务服务由接入者实现。本仓库源码尚未发布，各端实现、编译与运行验证范围见下文。

功能特色

适合哪些场景

下载与导入

从基础到进阶：按业务模块使用

模块一：无后台运行直播间业务

将示例页面加入项目 pages.json，所有宿主只导入 lizhao-live 一个插件。uni-app x 使用标准组件 lizhao-live；传统 uni-app 的 Android / iOS nvue 示例使用本插件内置的 lizhao-live-view 画面组件，普通 .vue 页面用于 Web、微信与 Harmony。默认媒体地址为空，不会假装开播。两种宿主调用根入口相同，uni-app 的 JavaScript 删除下例类型标注即可；完整可运行页面已经分别交付。内置nvue组件说明在 uni_modules/lizhao-live/docs/nvue-view.md。

import { createLiveSession, requestLiveBusiness, destroyLiveSession } from '@/uni_modules/lizhao-live'
import { LiveFailure } from '@/uni_modules/lizhao-live'

const session = createLiveSession({ roomId: 'mock-room-1', userId: 'mock-viewer' })
requestLiveBusiness({ action: 'joinRoom', sessionId: session.sessionId })
  .then((result) => { console.log(result.room, result.user, result.mock) })
  .catch((error: LiveFailure) => { console.error(error.errSubject, error.errCode, error.errMsg) })
// 页面退出时调用；不要只移除组件而遗留业务订阅。
function dispose(): void {
  destroyLiveSession(session.sessionId).catch((error: LiveFailure) => {
    console.error('释放未确认', error.errCode, error.errMsg)
  })
}

聊天使用 sendMessage 和 clientRequestId；同一请求重试复用该值，修改文本后换新值。订阅返回字符串 ID，退出时用 unsubscribeLiveRoom 解除。演示主播用户为 mock-host，mock-muted 为禁言演示用户；这些标识不是生产身份认证。

import { requestLiveBusiness, subscribeLiveRoom, unsubscribeLiveRoom } from '@/uni_modules/lizhao-live'
import { LiveFailure } from '@/uni_modules/lizhao-live'
const subscriptionId = subscribeLiveRoom(session.sessionId, (event) => { console.log(event.type, event.message) })
requestLiveBusiness({ action: 'sendMessage', sessionId: session.sessionId, text: '你好', clientRequestId: 'message-001' })
  .then((result) => { console.log(result.messages) })
  .catch((error: LiveFailure) => { console.error(error.errCode, error.errMsg) })
function stopSubscription(): void { unsubscribeLiveRoom(subscriptionId) }

模块二：真实开播与观看

在示例的“接入”页填入自己的媒体地址，切到主播台预览、推流、静音或切镜。绑定画面并收到组件 load 后才启动媒体。下例使用已有有效 session，并从你的服务端取得 mediaUrl；该变量是调用方准备的运行时数据，不是随插件交付的测试服务。

import { controlLiveMedia, getLiveCapabilitiesSync, onLiveEvent, offLiveEvent } from '@/uni_modules/lizhao-live'
import { LiveFailure } from '@/uni_modules/lizhao-live'
console.log(getLiveCapabilitiesSync())
const eventId = onLiveEvent((event) => { console.log(event.type, event.state, event.errCode) })
function startPush(mediaUrl: string): void {
  controlLiveMedia({ sessionId: session.sessionId, operation: 'push', url: mediaUrl })
    .then((result) => { console.log(result.state, result.dataJSON) })
    .catch((error: LiveFailure) => { console.error(error.errSubject, error.errCode, error.errMsg) })
}
function stopPush(): void {
  controlLiveMedia({ sessionId: session.sessionId, operation: 'stop' })
    .catch((error: LiveFailure) => { console.error('停止未确认', error.errCode, error.errMsg) })
  offLiveEvent(eventId)
}

观看将 operation 改为 play，传实际 HTTP(S) HLS .m3u8 地址；微信还可用其平台允许的 RTMP / FLV live-player 地址。HLS 有分片延迟，不等于实时连麦。推流成功表示内核取得实际连接/发布回执，播放成功按各端首帧或播放进度确认；不要把权限获准、按钮点击或 API 命令受理当成开播。

模块三：商品、规格与订单意图

listProducts 返回产品、skus、整数分价格和库存。以返回的真实商品与规格 ID 调用 createOrder；价格由适配器或服务端计算，页面不传可信总价。

import { requestLiveBusiness } from '@/uni_modules/lizhao-live'
import { LiveFailure } from '@/uni_modules/lizhao-live'
requestLiveBusiness({ action: 'listProducts', sessionId: session.sessionId })
  .then((result) => {
    if (result.products.length == 0 || result.products[0].skus.length == 0) { return }
    const product = result.products[0]
    requestLiveBusiness({ action: 'createOrder', sessionId: session.sessionId, productId: product.id,
      skuId: product.skus[0].id, quantity: 1, clientRequestId: 'order-001' })
      .then((orderResult) => { console.log(orderResult.order, orderResult.mock) })
      .catch((error: LiveFailure) => { console.error(error.errCode, error.errMsg) })
  }).catch((error: LiveFailure) => { console.error(error.errCode, error.errMsg) })

Mock 仅返回 mock-intent，不扣库存、不付款，不以假支付成功掩盖未接入交易。消息上限500条，演示订单上限200个；数据在进程重启或恢复独立 Mock 后丢失。

模块四：接入自己的业务接口

跨 JS / Native 使用通知-应答桥。原生回调不能依赖 JS 返回 Promise 或函数；setLiveBusinessAdapter 仅用于同语言执行环境（如 Web 或原生 UTS 内部），普通 App 页面推荐下例 JSON 桥。请求回调返回 void；异步结果通过 replyLiveBusinessBridge 应答。HTTP 地址由接入者配置，以下函数接收实际后端入口，不包含后台实现。

import { setLiveBusinessBridge, replyLiveBusinessBridge, publishLiveRoomEvent,
  setLiveBusinessAdapter } from '@/uni_modules/lizhao-live'
import { LiveBusinessBridgeEvent } from '@/uni_modules/lizhao-live'

function installHttpBusiness(apiUrl: string): void {
  setLiveBusinessBridge('自有业务接口', (eventJSON: string) => {
    const event = JSON.parse<LiveBusinessBridgeEvent>(eventJSON)
    if (event.kind != 'request') { return }
    uni.request({ url: apiUrl, method: 'POST', data: event.requestJSON,
      header: { 'Content-Type': 'application/json' },
      success: (response) => {
        if (response.statusCode >= 200 && response.statusCode < 300) {
          const payload = JSON.stringify(response.data)
          replyLiveBusinessBridge(event.requestId, payload ?? '', '')
        } else {
          replyLiveBusinessBridge(event.requestId, '', JSON.stringify({ errCode: 9391010,
            errMsg: '业务HTTP状态=' + response.statusCode.toString() })!)
        }
      },
      fail: (_error) => { replyLiveBusinessBridge(event.requestId, '',
        JSON.stringify({ errCode: 9391010, errMsg: '请求失败；有副作用的结果需向服务端查询' })!) }
    })
  })
}
// WebSocket收到该subscriptionId所属的LiveRoomEvent JSON时调用：
function deliverRoomEvent(subscriptionId: string, eventJSON: string): boolean {
  return publishLiveRoomEvent(subscriptionId, eventJSON)
}
function restoreLocalMock(): void { setLiveBusinessAdapter(null) }

uni-app JavaScript 使用 JSON.parse(eventJSON)，删除类型标注、泛型和非空断言。以上 HTTP 片段只接请求；完整实时消息接入需同时处理 bridge 的 subscribe / unsubscribe 通知：按 subscriptionId 建立或复用 WebSocket，订阅 roomId，收到 LiveRoomEvent 后 publishLiveRoomEvent，取消时关闭对应订阅和闲置连接。不要在收到订阅通知时伪造消息或观看人数。认证令牌仅内存传递，服务端检查签名，不信任客户端 userId / mock-host / totalFen。

服务端必须返回完整 LiveBusinessResult（action一致、mock:false；rooms/messages/products为空也返回数组，room/user/order缺省返回null，cursor/message返回字符串，hasMore返回布尔）。不要只返回 data 或 code 包裹对象。失败只传 failureJSON，成功只传 resultJSON，恰好一种。响应最多1Mi字符、单事件最多64Ki字符；迟到、重复或已经释放的应答返回false。请求15秒超时；超时、取消、网络断开后的发送/订单结果可能未知，查询或使用原clientRequestId幂等重试。

API 用途速查

会话与媒体参数

业务参数与动作

结果、事件与释放合同

完整强类型声明在 uni_modules/lizhao-live/utssdk/interface.uts。业务结果统一包含action、mock、rooms、room、user、messages、products、order、cursor、hasMore、message。金额priceFen/totalFen为整数分；事件/日志time和createdAt为Unix毫秒。

LiveMediaResult包含sessionId、requestId、operation、state、dataJSON。LiveEvent包含type（state/error）、state、errCode、message、dataJSON与关联ID。状态包括idle、preparing、ready、connecting、streaming、playing、stopping、stopped、error、released。原生dataJSON保留实际编码、连接或清理结果，不能只凭state文本替代诊断。

同步入口参数/会话错误抛LiveException；Promise接口reject LiveFailure，不使用success/fail/complete回调；每个Promise最多结算一次。持续监听用off/unsubscribe解除。destroy与release清除业务订阅和待处理请求；界面切后台应stop，页面退出destroy并off媒体监听。媒体事件日志默认600条、有估计字节上限并保留淘汰数量，不默认上传。

错误码说明

errSubject固定为lizhao-live；所有端使用相同含义，错误含errCode、errMsg、operation、sessionId、requestId、nativeType、nativeStack（采集不到时为空）。

WHIP POST已发送但未取得可删除资源Location时，停止只保证本地tracks/peer关闭，可能返回9391007并标记WHIP_CREATION_RESULT_UNKNOWN；迟到Location会尝试DELETE。需要服务端会话过期回收。取消、超时及网络失败不能推定订单未创建或远端发布已停止。

注意事项

平台、宿主与验证边界

当前是候选源码：实际HX资源编译、独立原生协议/SDK验证及Chrome验证与完整双宿主设备验收分层记录。没有Apple SDK完整链接、iOS/Harmony/微信真机与完整App宿主媒体/剪贴板验收时，平台声明保留待验，不将源码存在当作已支持。开发验证索引保留在项目内部记录，发布前应补齐匹配基座与目标真机矩阵。

Android/iOS/Harmony使用系统框架，没有打包商业直播SDK；Harmony随源码包含可复现自有NAPI HAR及所需许可。Web固定hls.js light仅HLS播放时动态加载，许可证与来源在 uni_modules/lizhao-live/utssdk/web/vendor/。单文件、HAR、独立同壳APK增量与最终宿主包体口径不同，不能相互替代。

iOS建议480×640、720×1280、1080×1920或对应横向，15–30fps、视频200000–8000000bps、音频32000–128000bps；系统实际能力仍可能拒绝。iOS17.4+要求可用硬编，较低系统由系统选择，不能声称已实测硬编。Harmony当前固定竖向采集，旋转/切镜需停止重建连接。原生各端不能因创建16个业务会话就承诺16路摄像头并发。

权限、网络与隐私

Android Manifest、iOS Info.plist/隐私清单、Harmony module.json5 已随平台源码提供摄像头、麦克风、网络用途声明；实际系统提示由对应平台按需触发。只预览时不额外请求无关权限。相机/麦克风可能被其他应用占用。Web需安全上下文、用户手势和浏览器许可；HLS跨域需正确CORS，WHIP需允许POST/DELETE及暴露Location；跨域媒体分片应使用服务端签名URL。

应用发布仍需接入方在隐私说明中披露音视频发送目的和目标服务；服务地址、Token与业务数据由接入方管理，不内置密钥。日志脱敏URL查询、令牌、账号路径等，复制前仍应检查业务自定义文本。高频日志有条数/估计字节边界和淘汰计数。报告构建HX、包类型或硬件信息无法采集时明确unknown，不拿开发电脑版本冒充安装包构建版本。

生命周期、报告与基座

原生UTS、Swift/Kotlin/ETS、依赖、权限、资源或组件变化后，必须重新原生联编或制作匹配自定义基座；WGT/appResource不能更新旧基座中的原生代码。仅文档或普通页面调整通常无需重打原生基座。传统App先运行nvue示例，不使用Web DOM承载原生画面。

示例底部提供一键复制、更新固定报告、分段复制及失败时手动文本回退；报告含真实版本来源、源码标记、脱敏完整保留日志及首尾校验标记。每段仅在实际剪贴板回读一致后推进。Windows Web在生成快照时采用CRLF，其他平台按实际文本格式；不放宽回读校验伪造成功。跨端剪贴板与系统权限需各端真机验收。

管理后台、真实IM/在线人数、鉴权服务、媒体服务器、CDN、库存、支付/退款、风控与合规审核均由接入者自行提供。本插件不承诺零服务器费用或低延迟连麦。

作者系列 UTS 插件