Unity 微信小游戏视频播放实战：VideoPlayer 与 WXVideo 2 种方案，从跑通到上线-育师

Unity 微信小游戏视频播放实战：VideoPlayer 与 WXVideo 2 种方案，从跑通到上线

【免费下载链接】minigame-unity-webgl-transform微信小游戏Unity引擎适配器文档。项目地址: https://gitcode.com/GitHub_Trending/mi/minigame-unity-webgl-transform

在微信小游戏里做 Unity 游戏，视频一卡，用户就划走。小游戏中要播过场动画、开场广告或加载视频，实际只有两条路：引擎内的 VideoPlayer，或小游戏原生的 WXVideo API。适配器仓库 minigame-unity-webgl-transform 对这两条路都做了适配，并留下了可直接运行的 Demo。这篇把配置、加固和上线检查清单一次讲完。

方案选型速查

方案	适用场景	渲染层级	播放限制	最低支持版本
VideoPlayer	游戏内过场、UI/场景中嵌视频	引擎内，可进 Render Texture 或 Camera Near Plane	iOS 高性能模式同时只能播 1 个	iOS 高性能+ 8.0.55 / iOS 高性能 8.0.41 / 安卓 8.0.40 / PC 基础库 3.2.1
WXVideo API	全屏广告、开场视频、需要在视频上盖 UI	原生层，`underGameView`可放在游戏画布之下	官方 QA 未明确条数限制	基础库 3.2.1（开发者工具需 3.2.1 + 1.06.2310312）

判断逻辑：视频要"长在游戏里"（渲染到 3D 场景或贴到 UI），选 VideoPlayer；纯全屏、或想压在游戏画布下面再叠一层交互 UI，选 WXVideo。混用也可以：小窗过场走 VideoPlayer，全屏广告走 WXVideo。路径来源见仓库 AudioAndVideo.md。

核心实现

最小配置：VideoPlayer 与 WXVideo 跑通主流程

VideoPlayer 已被导出插件自动适配，路径支持 CDN、微信本地文件、streamingAssets 三类。下面这段把场景里的 VideoPlayer 接到 streamingAssets 里的视频并开播：

using UnityEngine.Video; [RequireComponent(typeof(VideoPlayer))] public class CutscenePlayer : MonoBehaviour { void Awake() { var vp = GetComponent<VideoPlayer>(); // 本地文件路径，新版导出插件已支持 vp.url = System.IO.Path.Combine(Application.streamingAssetsPath, "cutscene.mp4"); vp.Play(); } }

全屏场景用 WXVideo，仓库 Demo/WX_Video 里有一个可跑示例。最小可用的创建与回调代码如下：

var info = WX.GetSystemInfoSync(); var video = WX.CreateVideo(new WXCreateVideoParam() { src = videoUrl, // CDN 地址 controls = false, autoplay = true, underGameView = true, // true：播在游戏画布之下 width = (int)info.screenWidth, height = (int)info.screenHeight, }); video.OnPlay(() => Debug.Log("onPlay")); video.OnError(() => Debug.Log("onError"));

加固：资源释放、错误回调与单视频队列

改之前：每次播放都新建，播完不销毁，错误回调也不接。原生视频对象会越攒越多，内存只升不降。

// 改之前：对象只增不减 video = WX.CreateVideo(param);

改之后：先销毁再创建，错误走 LogError，停止时显式 Destroy。对照仓库 API_V2 Demo 的写法，创建前都会检查_video != null并先 Destroy：

private WXVideo _video; public void PlayVideo(string url) { _video?.Destroy(); // 重建前先释放旧对象 _video = WX.CreateVideo(BuildParam(url)); _video.OnError(err => Debug.LogError("视频错误: " + err)); } public void StopVideo() { _video?.Destroy(); // 播放结束必须回收 _video = null; }

⚠️ 另一条硬约束：iOS 高性能模式下 VideoPlayer 同时只能播一个（iOS 播放策略，官方 QA 明确）。生产环境把多个过场视频排成队列顺序播，别写并行假设。

打磨：本地缓存与自适应码率

仓库 QA 明确：最新导出插件支持把视频缓存到本地文件路径，第二次播放不用重复下载。插件的 Loader 层本来就有"有缓存先读缓存"的请求流程：

这段代码实现"先查本地缓存，没有再走 CDN"的取址逻辑：

// 取播放地址：本地缓存优先，命中则跳过下载 string ResolveVideoUrl(string cacheKey, string cdnUrl) { // AccessSync 成功返回 "access:ok" return WX.GetFileSystemManager().AccessSync(cacheKey) == "access:ok" ? cacheKey : cdnUrl; // 未命中：先用 CDN 播，后台下载转存本地供下次用 }

自适应码率方面，视频规范建议码率低于 800 kbit/s，可以按网络档位准备多档转码：

// 用基础库 wx.getNetworkType 取网络类型，映射到对应码率档 string PickUrl(string networkType) { if (networkType == "wifi") return highUrl; // 高档 if (networkType == "4g") return midUrl; // 中档 return lowUrl; // 弱网低档 }

故障排查手册

iOS 有声无画（VideoPlayer）

症状：iOS 上声音正常，画面黑屏；其他平台正常。
根因：开启了高性能+但导出插件版本过旧；或代码里设置了videoPlayer.frame，iOS 不支持该属性。
修复：1. 升级到最新导出插件重新导出；2. 全局搜索并删掉videoPlayer.frame的赋值。

iOS 播不了视频，安卓正常（跨域）

症状：只有 iOS 播不了，其余平台都正常。
根因：视频服务器没放行微信源头的跨域访问。Origin weapp://wechat-game-runtime is not allowed by Access-Control-Allow-Origin这个错误不会打印到客户端，所以现象很隐蔽。
修复：1. 先把源换成微信官方测试视频链接隔离问题，测试链接能播就说明是服务端配置；2. 在 CDN/服务器配置 CORS，放行微信小游戏来源；3. 顺带确认 Content-Type 为 video/mp4。

WXVideo 真机正常但开发者工具不播

症状：真机播放一切正常，开发者工具里无反应。
根因：开发者工具暂存异常。
修复：手动把开发者工具基础库切到 3.4.10 再验证；工具结果不作为真机标准。

开启 underGameView 后 iOS 黑屏

症状：underGameView = true之后 iOS 上黑屏、有声音。
根因：没有开启高性能模式；透明画布依赖该模式。
修复：1. 在微信后台为该小游戏开启 iOS 高性能模式；2. 核对主相机 Clear Flag 为 Solid Color 且背景为黑色；3. 确认工程 Plugins 目录已放入 TransparentBackground.jslib。

iOS 一次只能播一个视频

症状：iOS 高性能模式下第二个 VideoPlayer 起播失败。
根因：iOS 自身播放策略限制，不是代码 bug。
修复：业务层把视频排队，播完一个再起下一个；确有同时播放需求的场景，改用 WXVideo。

性能基准与监控

参考环境：iPhone 13 Pro Max（微信机型档位映射中的参考机型），微信客户端 8.0.55+（iOS 高性能+最低版本），仓库 Demo 工程对应 Unity 2021.3。视频专项的内存/CPU 数值仓库未提供实测值，指标口径以官方评测标准为准，帧率与卡顿率取核心玩法 5 分钟以上均值。

指标	建议值	来源
视频文件大小	≤ 10MB	video.md Loading 视频规范
码率	< 800 kbit/s	video.md 建议参数
编码	H.264 / MP4（Main Profile），音轨 AAC 44.1kHz	video.md
帧率	24 FPS	video.md
播放期帧率/卡顿率	按官方档位标准	PerfMeasure.md

📌 仓库 Benchmark 工程有分场景、分设备的对比基线，下图为其测试场景在不同设备上的耗时柱状图。视频播放场景可用同样方法：开启/关闭视频各跑一轮，对比差值。

持续追踪建议盯"卡顿"：WXVideo 的 OnWaiting 在等待数据时触发，OnTimeUpdate 恢复播放，两者间隔就是卡顿时长：

void BindMonitor(WXVideo video) { float stallStart = 0; video.OnWaiting(() => stallStart = Time.realtimeSinceStartup); video.OnTimeUpdate(e => { if (stallStart > 0) { float dur = Time.realtimeSinceStartup - stallStart; stallStart = 0; if (dur > 0.5f) ReportStall(dur); // 卡顿超 0.5s 上报 } }); video.OnError(err => ReportError(err)); // 错误计数上报 }

开发版/体验版还可以直接开平台的最佳实践检测，自动输出帧率与启动建议：

// minigame/unity-namespace.js unityNamespace.monitorConfig = { enableMonitor: true, fps: 10 };

上线检查清单

导出前：

确认视频编码 H.264、容器 MP4（Main Profile）、音轨 AAC
码率压到 800 kbit/s 以内，文件 ≤10MB，时长 6~15 秒（Loading 视频）
按横屏 960×540 或竖屏 750×1334 导出，匹配屏幕比例
（underGameView 场景）主相机 Clear Flag 设为 Solid Color，背景黑色
（underGameView 场景）TransparentBackground.jslib 已放入工程 Plugins 目录
代码中已移除 videoPlayer.frame 赋值

提审前：

按最低版本真机逐一验证 VideoPlayer（iOS 8.0.41 / 高性能+ 8.0.55、安卓 8.0.40）
CDN 已配置 CORS 放行微信来源，并用真机验证视频 URL
WXVideo 在开发者工具异常时，切基础库 3.4.10 复核
iOS 高性能模式验证"单视频"队列逻辑
停止/重播路径都触发过 WXVideo Destroy

上线后：

统计卡顿时长（OnWaiting→OnTimeUpdate 间隔）与 onError 次数
定期看视频文件的 CDN 命中率与下载量
客户端或基础库大版本升级后，回归 iOS 播放兼容性

Unity 微信小游戏视频播放实战：VideoPlayer 与 WXVideo 2 种方案，从跑通到上线