一行配置让网页播放 360° 全景视频：ZWPlayer VR 实战

把一段 360° 全景视频放进普通网页播放器，得到的是一张被「摊平」的扭曲长条；要还原成球面环顾，播放器得用 WebGL 做投影渲染——自研通常以周计。ZWPlayer（v3.3.1 起）把这套渲染封装成了 vr 一个配置项。本文把它的三种形态、三种模式、视角预设、交互与排查逐一讲透，你只需要复制代码。

先看问题：不开 VR 时全景视频长什么样

360° 全景视频以等距柱状投影存储，画幅接近 2:1。普通播放器直接显示，就是下面这张「世界地图」——内容都在，但视角是歪的，完全没法看：

未开启 VR 时的全景素材 图 1:2:1 全景素材按普通视频平铺显示——画面被摊平变形

开启 VR 模式后，播放器把画面贴回球面内壁、视角置于球心，看到的就是正常的第一人称环顾画面（效果见《VR 视频播放器怎么选》图 1）。

vr 参数的三种形态

const player = new ZWPlayer({
  playerElm: 'player',
  url: 'https://example.com/panorama.mp4',
  vr: true,            // 形态一：布尔值
});

vr 接受三种写法，语义各不相同：

写法 语义 适用
vr: true 强置模式：进入页面即按全景渲染，隐藏原始 video 页面只为全景而生（全屏沉浸页、展厅大屏）
vr: 'auto' 自动模式：检测到画幅约 2:1（或 1:1 立体）自动进入 VR；普通视频照常平铺 同一页面混播全景与普通视频
vr: { ... } 对象模式：精确控制模式、按钮、初始视角等 生产环境推荐，参数见下文

不设置或 vr: false 则完全不启用 VR，零开销。

对象模式：把控制权拿到手

const player = new ZWPlayer({
  playerElm: 'player',
  url: 'https://example.com/panorama.mp4',
  vr: {
    mode: 'auto',       // 'force' 强置 | 'auto' 自动检测 | 'manual' 仅手动
    button: true,       // 控制条是否显示 VR 按钮
    yaw: 90,            // 初始水平偏航（度，0=正前，正值向右）
    pitch: -5,          // 初始垂直俯仰（度，0=水平，正值抬头）
    fov: 85,            // 初始视场角（度，30～100，越大视野越广）
    autoRotate: false,  // 桌面端无操作时缓慢自转（适合展示页）
    yawOnly: false,     // true 时锁定俯仰，只允许水平环顾
  },
  autoplay: false,
  controlbar: true,
});

几个语义细节值得展开：

  • mode: 'manual'：VR 能力与按钮就位，但由观众自己决定何时开启——适合「内容以平铺为主、全景只是彩蛋」的页面。
  • mode: 'force'：等价于 vr: true，加载即进入全景，连原始 video 都会隐藏，观众感知不到「切换」动作。
  • yaw/pitch/fov 是你的导演权：全景视频里观众第一眼看到哪里，由你决定。初始 FOV 75° 接近人眼；调小是「望远镜」，调大是「广角镜」。

运行时：按钮、菜单与交互

控制条上会出现 VR 按钮，点开出菜单：启用/禁用 VR、上下分屏立体声开关、VR 设置入口。

VR 菜单 图 2:控制条 VR 按钮与下拉菜单

进入全景后的交互不需要你写一行代码：

  • 鼠标拖拽（桌面）/ 手指滑动（移动端）：转动视角；
  • 滚轮：调整视场角，放大缩小。

另外，若素材画幅为 1:1（上下分屏的立体全景），播放器会自动识别并启用立体渲染，菜单里也可手动切换。

视角调试工作流：调好即复制

初始视角（yaw/pitch/fov）拍脑袋填是不行的——你的场景主角在哪个方位，只有看了才知道。ZWPlayer 内置了一个很实用的环路：

  1. 播放视频，点开 VR 设置 面板；
  2. 拖动滑块（左右视角 / 上下视角 / 视场角）实时预览，也可以直接在画面上拖拽，面板数值实时回同步；
  3. 满意后点复制配置，把当前视角导出为 vr 配置代码，粘回你的初始化参数即可。

VR 设置面板 图 3:VR 设置面板——滑块实时调视角，「复制配置」一键导出参数

拖拽与缩放视角 图 4:拖拽抬头望天并放大视场后的画面

这套「面板调参 → 复制配置 → 代码固化」的流程，比传统的「改代码→刷新→再改」快一个数量级。

不止 MP4：流媒体全景与全景直播

VR 模式与协议无关——MP4 直链、HLS（m3u8）、DASH、FLV、WebRTC 流都能切进全景视角。这意味着两类进阶玩法：

  • 大码率全景点播：4K～8K 全景文件动辄数 GB，转成 HLS/DASH 分片按需加载，观众拖动进度条不必等整个文件；
  • 全景直播：WebRTC 或低延迟 HLS 推全景流，观众在网页里边看边环顾——展会、赛事、景区慢直播都适用。

部署必读：CORS 与三个常见坑

坑一：黑屏，控制台报 SecurityError。 WebGL 读取跨域视频纹理要求视频源返回 CORS 头（Access-Control-Allow-Origin）。自己的 CDN/服务器加上响应头即可；无法控制源站时，可用自建反代（例如 ZWCorsProxy）补头。同源部署（视频与页面同域名）天然没有此问题。

坑二：开了 VR 画面仍是「摊平」的。 检查模式设置——mode: 'manual' 需要观众手动点 VR 按钮；素材画幅若不是 2:1（比如你裁过），'auto' 也不会触发，改用 force。

坑三：暂停时画面消失。 全景纹理依赖视频帧更新，部分浏览器在长暂停后不刷新纹理帧，恢复播放即正常。演示场景建议让视频保持播放或循环。

谁在用它

  • 文旅/房产：景区、酒店、样板房全景漫游，autoRotate 开启就是无人值守的展示页；
  • 教育：实验演示、历史场景复原，学生自主选择观察角度；
  • 安防：鱼眼/全景摄像头回放，VR 模式还原正常视角巡视各方向（配 RTSP 接入见《浏览器无插件播放 RTSP 流》）；
  • 活动直播：全景机位 + WebRTC 低延迟，网页端边看边转。

相关文章