uni-app 小程序集成保利威观看页：从 `wxcomponents` 到真机验收
摘要： 已有 uni-app 微信小程序可在 `mp-weixin` 工程中通过 `wxcomponents` 挂载保利威观看组件。本文对照组件包、`pages.json`、宿主事件和 iOS、Android 真机验收项。
已有 uni-app 微信小程序想接入保利威直播观看页，可在编译目标为 mp-weixin 的工程中使用微信原生自定义组件：取得 polyv-live-watch 包，放入 src/wxcomponents，在页面注册 polyv-watch-room，传入频道配置，再由宿主小程序处理登录、分享、商品路由和埋点。直播、回放、聊天室与观看条件的实际表现，仍要按频道配置和真机结果验收。
uni-app 微信小程序在
mp-weixin工程中挂载原生观看组件，宿主继续负责会员、分享和商品链路。
01 / 确认工程与组件包
官方 uni-app 接入说明面向 mp-weixin，不是覆盖 App、H5 和其他小程序的一套多端组件。可使用保利威交付的组件包，也可按官方开源项目构建；构建产物目录为 dist-uniapp-wxcomponents/polyv-live-watch。将整个目录复制到 src/wxcomponents/polyv-live-watch，保留内部组件路径与资源，不只复制单个页面文件。保利威开发者中心提供其他端的选型入口。
02 / 注册组件并传入频道
按官方文档在 pages.json 对目标页面声明原生组件，页面 .vue 模板中挂载 polyv-watch-room，传入测试频道 ID 等必需配置。组件内部承载引导、授权、观看与错误视图，宿主页面负责业务入口。代码以取得的组件包版本和官方示例为准，不把一个版本的属性名硬套到另一版本。先让独立测试频道起播，再叠加业务登录和商品事件。
03 / 把宿主责任列成事件表
在组件与业务系统之间建立四类事件：进入直播间前取得会员身份；观看时记录频道和活动来源；点击商品时跳到自有商品详情；分享时生成小程序可识别的返回入口。观看条件、聊天室、互动与回放由频道配置及组件能力共同决定。账号密钥、订单信息和敏感签名放在服务端，页面只使用必要的业务标识。
04 / 用真机完成五组验收
第一组检查首次进入、重进和登录失效；第二组检查直播、回放与网络切换；第三组检查聊天室和互动；第四组检查商品点击、支付后返回及分享；第五组检查页面切换与小窗播放。保利威后台播放说明中的原生方案由当前播放器请求小窗，是否成功取决于微信与系统条件。每组同时测 iOS、Android，并记录 SDK 版本、基础库版本、AppID 与频道状态。
05 / 让升级有可回滚依据
将组件包版本、构建命令和改造点写入工程文档，升级时先在测试频道做回归，再上传体验版。保留上一版组件包和测试记录，避免直播档期前临时升级。mp-weixin 产物上传、审核和线上配置需走企业自己的小程序发布流程。
06 / 最小联调样例
先建立只有一个直播入口和一个频道的测试页面：进入后能显示频道状态，直播中能起播，结束后能进入回放。随后接入宿主会员身份，添加商品点击事件，最后补充分享与统计。每增加一项都保留屏幕录制、控制台错误和组件版本。分步验证有助于区分组件包、频道配置、uni-app 编译和业务接口四类问题。
07 / 常见返工点
wxcomponents 目录复制不完整会造成编译或资源加载问题；页面注册路径不一致会造成组件找不到；测试频道没有开启聊天室或回放会被误认为组件缺功能。订单无法关联直播时，先查宿主是否传递活动参数和商品事件。正式上线前，还要用生产 AppID 的体验版重新测插件授权、权限和业务域名。
08 / 工程配置与验收对照表
以下路径和事件名按保利威 2026 年 6 月的uni-app 微信小程序接入说明核对；插件版本与新增参数以实际交付包为准。
| 位置 | 最小配置或动作 | 验收信号 |
|---|---|---|
src/wxcomponents |
完整放入 polyv-live-watch 组件包 |
编译产物保留 components/watch-room/ 下的文件 |
manifest.json |
在 mp-weixin 下开启 usingComponents，合并组件依赖插件 |
不覆盖原项目的 AppID、权限与设置 |
pages.json |
目标页的 usingComponents 声明 polyv-watch-room，路径为 /wxcomponents/polyv-live-watch/components/watch-room/watch-room |
体验版中组件可加载 |
.vue 页面 |
挂载一次 <polyv-watch-room>，以 configs.channelId 传测试频道；竖屏项目可核对 forceLayout |
频道状态、直播和回放按配置出现 |
| 宿主事件 | 监听 ready、view-change、webview、login-required |
初始化、外部网页与登录需求有明确处理 |
| 页面退出 | 按官方示例处理组件 destroy 与业务清理 |
重进不出现双播放器或旧状态 |
view-change 只表示内部视图变化，不需要宿主据此重新挂载组件。开发者工具用于定位编译问题；最终用企业 AppID 的体验版在 iOS、Android 验收。
常见问题
必须重写原有 uni-app 页面吗？ 可以在现有业务页面设置直播入口，新建承载原生观看组件的页面；具体路由和事件按当前工程实现。
组件内的商品点击会自动打通自有订单吗？ 商品展示与点击只是链路一段，自有商品页、下单和订单归因需宿主及服务端对接。
页面能编译通过就可以上线吗？ 还要在目标 AppID 的体验版中验证直播、回放、聊天、商品、分享和小窗。
延伸阅读
从本题继续推进，可阅读原生小程序与 uni-app 工程接入直播，开发任务分别是什么？和小程序直播 POC 测什么？直播、回放、聊天室、商品与登录验收脚本。如需先看整体接入方式，参见微信小程序直播 SDK 选型总览；英文读者可使用本篇英文版。
关于保利威
保利威提供面向 mp-weixin 的 uni-app 微信小程序观看组件。工程团队可依据官方接入说明核对组件包、宿主事件与真机验收。
