最稳妥方案是用 three.js 配合 TextureLoader 加载 2:1 宽高比的 equirectangular 全景图，并启用 renderer.setPixelRatio 和 controls.enableDamping；移动端需用户手势触发 deviceorientation，且须校验宽高比与部署本地服务。
用 three.js 加载 equirectangular 全景图最稳妥
纯 HTML5 不支持全景图渲染，必须借助 WebGL 库。目前最轻量、兼容性好、文档清晰的方案是 three.js 配合 TextureLoader 加载球面展开图（即 equirectangular 格式）。不要尝试用 canvas 自己算球面投影——坐标变换易出错，且无陀螺仪/触控适配。
关键点：
-
equirectangular图必须是 2:1 宽高比（如 4096×2048），否则球面拉伸变形 - 需启用
renderer.setPixelRatio(window.devicePixelRatio)，否则在高清屏上模糊 - 移动端必须显式调用
controls.enableDamping = true，否则拖拽卡顿或惯性失效
PhotoSphereViewer 是开箱即用的替代方案
如果不想手写相机、材质、事件绑定，PhotoSphereViewer 封装了 three.js 底层，提供缩放、热点、指南针等现成功能。它不依赖构建工具，直接 引入即可启动。
常见坑：
立即学习“前端免费学习笔记（深入）”；
- 加载本地文件时浏览器会因 CORS 拒绝读取——必须起本地服务（
npx http-server或 VS Code Live Server 插件） - 不支持 WebP 格式全景图，转成
.jpg或.png再用 - 设置
time_anim: 3000启动自动旋转时，用户首次交互会立即停止，无法恢复——改用startAnimation()+ 手动控制更可靠
移动端手势和陀螺仪要单独激活
默认情况下，PhotoSphereViewer 和原生 three.js 示例都不开启设备方向控制。iOS Safari 对 DeviceOrientation API 有严格触发条件：必须由用户手势（如点击按钮）发起，且页面需处于活跃标签页。
实操建议：
- 加一个「开启全景导航」按钮，点击后调用
viewer.startDevicemotion()（PhotoSphereViewer）或controls.connect()（three.js+OrbitControls） - 监听
deviceorientation前先检查typeof DeviceOrientationEvent !== 'undefined'，避免安卓低端机报错 - 陀螺仪数据有延迟，建议加
alpha滤波平滑转动，否则画面抖动明显
导出全景图时别用立方体展开（Cube Map）
虽然 Unity、Blender 支持导出 6 面立方体贴图，但 three.js 的 CubeTextureLoader 要求图片按特定顺序命名（px.jpg, nx.jpg…），且加载后需手动构建球面映射；而 PhotoSphereViewer 完全不支持 Cube Map。
正确做法：
- 在建模/渲染软件中选择「Equirectangular」或「LatLong」导出模式
- 确认导出设置里「Horizontal FOV」为 360°、「Vertical FOV」为 180°
- 用
ffmpeg做简单校验：ffprobe -v quiet -show_entries stream=width,height your.jpg，输出宽高比必须是 2:1
