更新记录

1.0.0（2026-11-15）

• 新增面向 HarmonyOS 平板整屏采集并发布到 SRS/RTMP 的稳定版插件合同，保留 H.264 Surface 编码、可选麦克风 AAC、事件和诊断能力。
• 修复带 ?txSecret、?auth_key 等 SRS 签名查询参数的 RTMP 地址被公共校验拒绝的问题，并统一端口范围校验。
• 修复启动与停止请求关联编号可能重复的问题，补齐 DNS、握手、连接和断开失败到统一 RTMP 错误码的映射。
• 优化 uni-app x 示例的根入口类型导入和宿主诊断标记，统一 Harmony HAR、配置和构建元数据为 1.0.0。

平台兼容性

uni-app(5.34)

uni-app x(5.34)

lizhao-screen-push Harmony 屏幕 RTMP 推流 UTS 插件

介绍

lizhao-screen-push 面向 uni-app Vue3 与 uni-app x 的 HarmonyOS 宿主，把用户确认的系统屏幕采集直接编码并发布到 SRS 等 RTMP 服务；默认无音频，可选麦克风音频，源码与验证状态以本说明为准。

功能特色

适合哪些场景

下载与导入

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

模块一：检查能力并启动

页面只从插件根入口导入。url 是接入方准备的实际 SRS 地址，不会由插件猜测或内置。地址可以带 SRS 常见的签名查询参数，例如 ?txSecret=...&txTime=...，插件会在诊断和报告中脱敏。Harmony 首次启动会出现系统录屏确认，用户拒绝时 Promise 会以 9392005 失败。

import { getScreenPushCapabilitiesSync, startScreenPush } from '@/uni_modules/lizhao-screen-push'

const capabilities = getScreenPushCapabilitiesSync()
if (!capabilities.supported) {
  console.error(capabilities.verification)
} else {
  startScreenPush({
    url: 'rtmp://192.168.1.10/live/pad-1',
    audioSource: 'none'
  }).then((session) => {
    console.log(session.sessionId, session.urlHost, session.width, session.height, session.fps)
  }).catch((error) => {
    console.error(error.errSubject, error.errCode, error.errMsg)
  })
}

模块二：可选麦克风与事件

麦克风是显式选择项，默认值为 none。启用后由 Harmony 系统请求 ohos.permission.MICROPHONE；权限失败不会伪装成无声推流成功。

import { onScreenPushEvent, offScreenPushEvent, startScreenPush } from '@/uni_modules/lizhao-screen-push'

const listenerId = onScreenPushEvent((event) => {
  console.log(event.type, event.state, event.errCode, event.detail)
})
startScreenPush({ url: 'rtmp://192.168.1.10/live/pad-1', audioSource: 'microphone', audioBitrate: 64000 })
  .catch((error) => console.error(error.errCode, error.errMsg))
// 页面退出或不再需要事件时释放监听器。
offScreenPushEvent(listenerId)

模块三：停止与重启

停止操作应使用启动成功返回的 sessionId。启动尚未返回 sessionId 前没有可取消的公开句柄，页面应在启动 Promise 完成后再允许停止；页面销毁时对已返回的会话调用 stopScreenPush。重复停止、页面已经没有活跃会话时返回 state: 'stopped' 的幂等结果；释放失败会保留原生错误，不能根据按钮点击推断远端已经停止。

import { stopScreenPush } from '@/uni_modules/lizhao-screen-push'

stopScreenPush(sessionId).then((result) => {
  console.log(result.state, result.dataJSON)
}).catch((error) => {
  console.error('停止结果未知', error.errSubject, error.errCode, error.errMsg)
})

模块四：诊断报告与复制

示例页底部的“一键复制日志”会固定一次快照，包含插件版本、源码构建标记、宿主运行信息、能力结果、会话和有界脱敏操作日志。报告超过剪贴板长度时使用“复制下一段”；只有剪贴板回读与固定段完全一致后才推进段号。回读失败时使用手动文本入口，不提示伪成功。

import { getScreenPushDiagnosticsSync } from '@/uni_modules/lizhao-screen-push'
const snapshot = getScreenPushDiagnosticsSync()
console.log(snapshot.pluginId, snapshot.version, snapshot.buildMarker, snapshot.entries.length)

API 用途速查

startScreenPush 参数

返回值、回调和事件

ScreenPushSession 包含 sessionId、state、脱敏后的 urlHost、实际尺寸、帧率、音频源和 startedAt。ScreenPushResult 包含 sessionId、requestId、state、dataJSON；原生清理细节只放在 dataJSON 和诊断日志中。

ScreenPushEvent 包含 sessionId、requestId、type、state、时间、errCode、errMsg 和 detail。当前原生事件类型包括 connected、screen-started、capturing、video-written、audio-written、mediaReady 和 error；原生错误事件会触发一次异步资源释放，业务仍应先读取错误字段和诊断，再决定是否重新启动。启动尚未完成时再次调用 startScreenPush 也会返回 9392004，避免两个编码会话并发进入原生层。事件监听器不会自动释放，页面退出时调用 offScreenPushEvent。

错误码说明

errSubject 固定为 lizhao-screen-push。Promise 失败对象包含 errSubject、errCode、errMsg、operation、sessionId、requestId、nativeType、nativeStack；采集不到的原生字段为空字符串。超时、取消和远端结果未知不会被当作确定成功或确定失败。

注意事项

平台与宿主支持范围

权限、隐私与生命周期

Harmony 模块声明网络权限；选择麦克风时才需要麦克风权限。屏幕采集由系统录屏确认处理，不申请与本能力无关的权限。屏幕内容和音频只发送到调用方提供的媒体地址，诊断默认只保存在本地内存并脱敏，不自动上传。

当前要求用户在应用前台启动并维持推流；系统内录音频、后台长期保活、锁屏继续推流和自动恢复列为后续扩展。页面隐藏或销毁时先调用 stopScreenPush，再解除事件监听；停止 Promise 未确认前不要立即启动同一路流名。

原生 ETS/C++、本地 HAR、权限、资源或 module.json5 变化后必须重新原生联编并制作匹配自定义基座；WGT 或 appResource 不能把新原生代码注入旧基座。没有 DevEco/Harmony 工具链、匹配自定义基座或真机时，只能报告静态和编译结果，不能把它描述成真机同屏通过。

资源与地址限制

RTMP 地址由接入方准备；日志会把完整媒体地址、查询参数和凭据统一脱敏。SRS 应为每台 Pad 分配不同流名，拉流端沿用现有播放链路。网络失败、DNS 超时、服务端拒绝或流名冲突都通过错误码与诊断报告返回，不会显示伪成功。启动阶段的授权、DNS 和 RTMP 发布握手仍在等待时，调用方尚未拿到 sessionId，只能等待 Promise 成功或失败；需要停止时使用成功结果中的会话编号。

作者系列 UTS 插件