uni-app 中直播挂件需用微信插件 live-player-plugin，仅支持微信小程序；H5/App 需降级；manifest.json 的 mp-weixin 下配置 provider、version、appid；分包需重复声明；跳转用 plugin-private 协议和 wx.navigateTo；room_id 为数字；custom_params 需编码且≤600字符；状态监听依赖后端信令；直播地址须签名且域名备案。
uni-app 无法直接使用 live-player 原生组件实现直播挂件功能，必须通过微信官方提供的插件 live-player-plugin 接入，且仅限微信小程序平台；H5 和 App 端无对应能力，需单独降级处理。
manifest.json 中正确配置 live-player-plugin 插件
插件必须在 manifest.json 的 mp-weixin 节点下声明，不能写在 pages.json 或 app.json 中（uni-app 会忽略）。provider 固定为 wx2b03c6e691cd7370，version 必须填实际可用版本号（如 1.3.2），不是“最新”或“latest”——微信开发者工具真机调试时，在「详情 → 插件」页能查到当前项目实际支持的版本，填错会导致插件加载失败、白屏或 plugin not found 报错。
-
appid字段必须与你在微信公众平台申请直播权限的小程序一致，否则插件初始化失败 - 若用分包加载，需在对应分包的
subNVue或subPackages配置中重复声明该插件（uni-app 不自动透传主包插件） - 插件不计入代码包体积限制，但首次加载有约 1–2s 延迟，建议提前
requirePlugin预加载
跳转到直播页面必须用 plugin-private 协议
不能用 navigator 组件硬编码 URL，也不能用 uni.navigateTo 直接跳 /pages/live/live 这类自定义路径。必须构造形如 plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=123&custom_params=xxx 的地址调用 wx.navigateTo（注意：是 wx，不是 uni）。
-
room_id是数字类型 ID，不能是字符串格式的房间号（比如带前缀room_123），否则进不去直播间 -
custom_params必须encodeURIComponent编码，且内容长度 ≤ 600 字符，超长会被截断导致参数丢失 - H5 端调用该 URL 会报错，务必加平台判断：
if (uni.getSystemInfoSync().platform === 'ios' || uni.getSystemInfoSync().platform === 'android') { /* app 降级逻辑 */ } else if (uni.getSystemInfoSync().platform === 'devtools') { /* 模拟逻辑 */ }
cover-view 包裹 live-player 时状态监听失效问题
微信要求直播画面必须用 cover-view + cover-image 做浮层控制，但 live-player 自身不支持 bindstatechange 等事件绑定在 cover-view 内——这些事件只能在原生 live-player 组件上监听，而插件内部已封装好 UI，你拿不到该 DOM 节点。
- 插件不暴露
LivePlayerContext，uni.createLivePlayerContext在插件页内无效 - 想监听播放状态（如卡顿、断连、暂停），只能依赖后端推送的 Websocket 信令，或轮询直播后台接口
/api/v1/room/status?room_id=xxx - 封面图、标题、点赞数等动态信息，必须由业务侧自己通过接口拉取并渲染在
cover-view层，插件不透出这些数据
直播地址签名和域名备案是上线硬门槛
即使插件配置全对、跳转无误，若直播流地址（如 rtmp://xxx.com/live/xxx）未由后端签发带有效 txTime 和 authKey 的防盗链 URL，或推流域名/播流域名未在微信公众平台完成 ICP 备案并添加到「直播域名白名单」，用户将看到黑屏或“加载失败”提示，且控制台无明确错误日志。
- 错误码
10004表示签名过期，10005表示域名未备案，10008表示 room_id 不存在或已关闭 - 测试阶段可用微信提供的测试流地址（如
rtmp://live.hkstv.hk.lxdns.com/live/hks），但上线前必须切换为自有已备案域名 - 微信后台「直播管理 → 域名管理」中添加的域名，必须与后端生成的播放地址中的 host 完全一致（包括 www 和非 www）
插件本身不处理网络重连、弱网降级、音画同步等细节，这些都得靠业务层兜底；最易被忽略的是 custom_params 截断和域名备案校验——它们不会报 JS 错误，只会在真机上静默失败。
