三种方案实测｜Unity 微信小游戏视频：VideoPlayer 与 WXVideo 从配置到调优的完整路径

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

这段话解决一个问题：Unity 微信小游戏的视频播放怎么做才稳。如果你已有基础 Unity 经验、正在落地视频功能，读完能直接拿到 VideoPlayer 与 WXVideo 的选择依据、可运行的配置步骤、一张实测数据表和一套高频故障速查。

方案全景：先搞清楚你手里有哪些牌

微信小游戏里能播视频的"牌"其实就两种：Unity 自带的 VideoPlayer 组件（导出插件已自动适配）和微信原生的 WXVideo API。前者把视频渲染进引擎，后者由小游戏容器直接托管。先把维度摊开：

解读一句话：VideoPlayer 的资源占用和 CPU 开销都更高，因为它走的是引擎的解码与渲染路径；WXVideo 由微信原生播放器托管，占用低、起播快，代价是你无法在引擎内拿到它的纹理。

选牌口诀：进场景选 VideoPlayer，纯全屏选 WXVideo，都要就混合并管住数量。

场景一：剧情动画，VideoPlayer 五步配好

适用条件：视频需要和游戏画面、UI 或 3D 对象发生交互（叠加、遮挡、贴图到面片上）。

1. 视频转成 H.264 编码的 MP4，放入StreamingAssets，或直接使用 CDN 地址（仓库的视频规范要求：MP4、H.264 Main Profile、时长 6~15 秒、体积不超 10MB）
2. 新建空 GameObject，挂载VideoPlayer组件
3. Source选 Video Clip（本地）或 URL（远程）
4. Render Mode按用途选：Camera 平面用于 UI 层，Render Texture 用于 3D 场景
5. Audio Output Mode设为 Direct，在逻辑合适的时机调用Play()

下面是动态加载远程或本地视频的最小片段，路径拼接用引擎 API 保证跨平台正确：

// 拼接 StreamingAssets 下的本地视频；远程 CDN 地址可直接赋给 url string videoPath = System.IO.Path.Combine( Application.streamingAssetsPath, "cutscene.mp4"); videoPlayer.url = videoPath; videoPlayer.Play();

写完后先跑一遍再谈优化：本地路径和 CDN 地址走同一套代码，后续换源不需要改逻辑。

Loading 视频在初始化期间循环播放的实况。

💡 容易忽略的点：url支持 CDN、微信本地文件路径、StreamingAssets 三类；最新导出插件支持把视频缓存到本地文件路径再播，能省掉重复下载。另外 iOS 高性能模式的系统策略决定它同一时间只能播一个视频，多视频并发只能在逻辑层排队（依据见 Design/AudioAndVideo.md）。

场景二：全屏广告，WXVideo + 透明画布

适用条件：视频铺满全屏、不需要与 3D 场景交互，且希望视频之上还能盖交互 UI（如跳过按钮）。

1. 克隆仓库获取完整示例工程：git clone https://gitcode.com/GitHub_Trending/mi/minigame-unity-webgl-transform，重点看Demo/WX_Video
2. 主相机 Clear Flag 改为 Solid Color，背景色设黑（透明画布的前提是"画布没内容的地方透出视频"）
3. 把Demo/WX_Video/Assets/Plugins/TransparentBackground.jslib拷入自己工程的 Plugins 目录，它拦截了 Emscripten 的glClear，避免清 alpha 时把透明画布洗掉
4. 修改minigame/unity-sdk/video.js支持透明画布（新版插件会自动改好）
5. C# 侧创建视频并监听回调

video.js需要补的核心逻辑（其余部分见 Demo 的 readme）：

WXCreateVideo(conf) { const params = JSON.parse(conf); if (params.underGameView) { GameGlobal.enableTransparentCanvas = true; } // ... 创建 videos[id] = wx.createVideo(params) 等逻辑省略 }, WXVideoDestroy(id) { if (videos[id]) videos[id].destroy(); GameGlobal.enableTransparentCanvas = false; // 销毁时务必关回 }

C# 侧按仓库示例（Demo/WX_Video/Assets/PlayVideo.cs）的最小调用：

var info = WX.GetSystemInfoSync(); var video = WX.CreateVideo(new WXCreateVideoParam { src = "https://your-cdn/ad.mp4", controls = false, autoplay = true, underGameView = true, // 关键：压到游戏画布之下 width = (int)info.screenWidth, height = (int)info.screenHeight }); video.OnError(() => Debug.Log("video on error"));

underGameView是这一方案的核心开关：视频层级默认在游戏之上，打开后画布不透明的地方显示游戏、透明处透出视频，跳过按钮等 UI 就能盖在视频上。

视频位于游戏画布之下，画布空白处透出视频。

⚠️ 容易忽略的点：iOS 上underGameView=true后出现有声黑屏，是高性能模式未开启；开发者工具里播放异常时，主动切到基础库 3.4.10 再判断，工具端偶有兼容问题（依据见 Demo/WX_Video/readme.md）。

场景三：混合策略，小窗走 VideoPlayer、全屏走 WXVideo

适用条件：游戏既有场景内小窗（教程回放、角色过场），又要投全屏广告。

1. 场景内视频统一用 VideoPlayer，全屏播放统一用 WXVideo，不混用
2. 收口到一个管理器，记录每个实例的"出身"（VideoPlayer 还是 WXVideo）
3. 切换前确认旧实例已完全销毁——两类的销毁方式不同
4. 限制同时存活的视频总数，混合场景内存是两类之和

// 统一出口：按类型走不同销毁路径 public void Release(string id) { if (id.StartsWith("wx_")) wxVideoMap[id].Destroy(); // WXVideo 必须手动 Destroy else Destroy(players[id].gameObject); // VideoPlayer 走引擎 // ... 从字典移除，省略 }

容易忽略的点：混合模式下内存峰值是两类叠加，iOS 高性能模式还受"单视频并发"限制，广告和剧情视频若同时触发要排队。

实测数据：内存和 CPU 各占多少

测试环境：iPhone 13 Pro Max，微信客户端 8.0.55，Unity 2021.3 LTS。

对普通项目意味着什么：单个全屏广告的内存峰值完全无感，真正需要上预算的是混合场景——35MB 的峰值足以在低配机把游戏挤进内存告警区，这正是下一节要做的事。

工程化加固：上线前必须做的三件事

内存管理：给视频数量装上限

同时播放的视频是内存大户，且 iOS 高性能模式系统层面只允许单路，所以"限制数量"不是建议而是必须：

private const int MaxConcurrent = 3; private readonly Dictionary<string, VideoPlayer> _playing = new(); public void Play(string id, string url) { if (_playing.Count >= MaxConcurrent) ReleaseOldest(); // 先腾位 _playing[id] = CreateAndPlay(url); } public void Stop(string id) { if (_playing.TryGetValue(id, out var p)) { p.Stop(); Destroy(p.gameObject); _playing.Remove(id); } }

• WXVideo 走另一条路：每次播完必须显式video.Destroy()，它不经过引擎对象生命周期
• 把 VideoPlayer 实例纳入对象池，避免反复 new/Destroy 造成抖动
• OnDestroy里兜底释放，防止协程挂死的场景把视频带出生命周期

预加载缓存：第二次播放走本地

用文件系统的AccessSync判断是否已缓存，未命中再下载。注意 SDK 的AccessSync返回值与官方文档描述不同：成功返回"access:ok"，失败返回具体错误信息，不抛异常（依据见 Demo/API_V2 的 FileSystem/Access 示例）：

private const string CacheDir = "video_cache/"; public bool IsCached(string name) { var fs = WX.GetFileSystemManager(); return fs.AccessSync(fs.userDataPath + CacheDir + name) == "access:ok"; } public void DownloadIfAbsent(string url, string name) { if (IsCached(name)) return; WX.DownloadFile(new DownloadFileOption { url = url, filePath = WX.GetFileSystemManager().userDataPath + CacheDir + name }); // 成功回调里再 Play，省略 }

• 缓存路径放userDataPath下，用"视频名+哈希"做 key，避免 URL 变更导致全部失效
• 对 Loading 视频这类必播资源，首包前就触发下载，别等用户看到黑屏再下

自适应码率：按网络给不同档

码率档位（1080p/720p/480p）提前转好挂在 CDN，运行时按网络类型选档。网络类型通过微信官方wx.getNetworkType接口获取后传入：

private string PickUrl(string networkType) { return networkType switch { "wifi" => "https://cdn.example/cut_1080p.mp4", "4g" => "https://cdn.example/cut_720p.mp4", _ => "https://cdn.example/cut_480p.mp4" }; }

• 480p 档保证弱网也能起播，宁可糊不能卡
• 切换档位要重建播放源，放在视频开始前的空隙做，别播到一半切
• 结合视频规范（码率 <800 kbit/s、时长 6~15 秒），弱网档位可再压一档

高频故障速查

iOS 有声无画面（黑屏）

• 现象：真机 iOS 播视频只有声音，画面黑屏，其他平台正常
• 根因：开启了高性能+但导出插件不是最新版；或代码里设置了videoPlayer.frame（iOS 不支持该属性）
• 修复：① 升级最新版导出插件 ② 删除所有对frame的赋值 ③ 确认视频为 H.264 编码的 MP4

开发者工具正常，真机播不了（CORS）

• 现象：工具里正常，真机静默失败，控制台没有明显报错
• 根因：服务端没放行微信运行时域名。真正的报错是Origin weapp://wechat-game-runtime is not allowed by Access-Control-Allow-Origin，但它不会打印到客户端，极易漏看（依据见 Design/AudioAndVideo.md）
• 修复：① 服务端响应头允许weapp://wechat-game-runtime跨域 ② 校验Content-Type为video/mp4③ 用官方测试视频复放，隔离"是自己的服务问题还是视频源问题"

反复播放内存持续上涨

• 现象：看广告循环几次后内存曲线只涨不落
• 根因：WXVideo 实例未销毁，或并发播放数失控
• 修复：① 每次播放结束显式video.Destroy()② 并发数压到 3 以内 ③ 用统一管理器持有全部实例引用，杜绝"播完就丢引用"的匿名视频

透明画布异常（underGameView 后画面发黑/花屏）

• 现象：设置underGameView=true后游戏画面整体异常
• 根因：TransparentBackground.jslib未导入，或主相机没有清成纯黑底色
• 修复：① 导入Demo/WX_Video/Assets/Plugins/TransparentBackground.jslib② 主相机 Clear Flag 设 Solid Color + 黑色 ③ 用新版插件（video.js会自动改好），或手动按 Demo readme 核对三处补丁

进阶玩法

视频上盖交互 UI：跳过按钮的正确打开方式

透明画布的意义就在这一步——视频在画布之下，UI Canvas 在之上，天然形成"视频 + 可点按钮"的叠加效果：

var video = WX.CreateVideo(new WXCreateVideoParam { src = videoUrl, autoplay = true, underGameView = true }); // overlayCanvas 上挂跳过按钮，排序高于背景层 skipButton.onClick.AddListener(() => { video.Destroy(); // 销毁视频，透明画布随 WXVideoDestroy 一并关闭 });

注意销毁顺序：先Destroy()视频，video.js里的WXVideoDestroy会把enableTransparentCanvas关回，画布恢复不透明——顺序反了会出现 UI 盖住自己游戏的怪象。

播放状态与游戏逻辑同步

剧情视频的每个关键时间点（爆炸、转场、台词）都要对齐游戏逻辑。VideoPlayer 在Update里做帧级轮询，WXVideo 用OnTimeUpdate事件驱动，两者别混用：

// VideoPlayer：帧级轮询 + 阈值去抖 void Update() { if (!videoPlayer.isPlaying) return; float t = (float)videoPlayer.time; if (Mathf.Abs(t - lastSync) < 0.1f) return; lastSync = t; SyncGameState(t); // 按时间点触发场景事件 } // WXVideo：事件驱动，注册后在回调里对齐逻辑 video.OnTimeUpdate(time => SyncGameState((float)time));

阈值去抖（0.1s）防止同一段逻辑每帧触发；事件驱动则完全省掉轮询开销，全屏视频推荐用它。

收尾行动清单

• 今天就能做：按"选牌口诀"定方案；给视频 CDN 配好 CORS 与video/mp4响应头
• 今天就能做：把 VideoPlayer 的Render Mode、Source按场景一第 3~4 步核对一遍
• 本周该做：落地并发上限 + 强制Destroy()的释放管理器
• 本周该做：Loading 视频接上预加载缓存（AccessSync+DownloadFile）
• 长期规划：按网络类型做多码率档位并建立弱网复测流程
• 长期规划：把视频播放纳入性能监控，告警阈值定在内存 35MB、帧率 30fps

延伸阅读

• VideoPlayer 支持版本表与 iOS 播放策略问答
• 视频制作规范：H.264 编码、时长与码率参数
• 微信小游戏性能优化的通用手段与工具
• WebGL 内存优化：泄漏定位与预算控制

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