HTML的<audio>标签不支持3D音效，因其规范缺失坐标系、HRTF等空间音频概念；必须用Web Audio API通过AudioListener与PannerNode构建空间音频链路，并注意移动端需用户手势触发context.resume()。
HTML 的 <audio> 标签本身完全不支持 3D 音效，加任何 data- 属性、CSS 3D 变换或 position 样式都无效。必须用 Web Audio API 手动构建空间音频链路，否则永远只是单声道/立体声播放。
为什么 <audio> 标签不能设 Listener 或位置
HTML5 音频规范里没有坐标系、听者朝向、HRTF 模型等概念。<audio> 只暴露 volume、playbackRate、muted 这类基础控制，所有空间计算必须由 JavaScript 在 AudioContext 中完成。
- 试图给
<audio id="bgm">加data-position="5,0,-3"—— 完全被忽略，无任何效果 - 用 CSS
transform: translateZ(-100px)动画 audio 元素 —— 视觉位移 ≠ 声音位移，音频输出毫无变化 - 直接
audio.play()后调audio.positionX = 5—— 报错：audio.positionX is not a function，因为原生元素没这个属性
必须用 AudioListener + PannerNode 搭建链路
Web Audio API 的空间模型是“听者固定、声源移动”：一个全局唯一的 context.listener，配合多个可定位的 PannerNode。两者缺一不可。
-
context.listener必须手动设置朝向：listener.forwardZ.value = -1（默认正前方），listener.upY.value = 1（头顶朝上） - 每个声源必须走
MediaElementSourceNode → PannerNode → destination，跳过PannerNode就等于放弃空间化 -
PannerNode要显式启用 HRTF：panner.panningModel = 'HRTF'；若浏览器不支持会静默降级为'equalpower'（仅左右平移） - 坐标单位是米，右手系：X 向右、Y 向上、Z 向前（不是屏幕深度方向）
移动端首次播放必须由用户手势触发
iOS Safari 和 Android Chrome 强制要求：AudioContext 初始为 suspended 状态，不响应任何播放或参数更新，直到用户点击/触摸页面某处。
立即学习“前端免费学习笔记（深入）”；
- 常见错误：页面加载完自动
audio.play()→ 控制台报The play() request was interrupted - 正确做法：绑定按钮 click 事件，在回调中先
context.resume()，再audio.play()或source.start() - Listener 位置更新也得在该事件后才生效，比如
button.addEventListener('click', () => { listener.positionX.value = 2 })
动态切换音频源时别断开 PannerNode
想换歌但保持同一空间位置？不要销毁重建 PannerNode，它保存着所有空间参数（position、orientation、distanceModel）。
- 错误操作：每次换音源都
context.createPanner()→ 丢失之前设好的坐标和朝向 - 正确操作：复用已有
pannerNode，只替换上游 source：oldSource.disconnect(pannerNode); newSource.connect(pannerNode) - 注意
MediaElementSourceNode不能重复 connect，需先disconnect()再重连 - 如果用
AudioBufferSourceNode，记得每次start()前重新创建实例（它是一次性的）
最容易被忽略的是 Listener 的朝向初始化——很多人只设了 positionX/Y/Z，却忘了 forwardX/Y/Z 和 upX/Y/Z 默认值在某些设备上会导致声音反向或塌陷。哪怕只是做个简单环绕 demo，也得显式写一遍 listener.forwardZ.value = -1 和 listener.upY.value = 1。
