UniApp 音频播放技术文档

UniApp 音频播放技术文档

一、基础实现方案

1. 使用 InnerAudioContext（原生 API）

// 创建音频实例
const audioContext = uni.createInnerAudioContext()

// 配置音频参数
audioContext.src = '/static/audio/beep.mp3' // 支持本地和远程路径
audioContext.volume = 0.8 // 音量范围 0~1
audioContext.loop = false // 是否循环播放

// 事件监听
audioContext.onPlay(() => console.log('开始播放'))
audioContext.onError((err) => console.error('播放错误', err))

// 播放控制
audioContext.play()  // 开始播放
audioContext.pause() // 暂停播放
audioContext.stop()  // 停止播放

// 销毁实例（重要！）
audioContext.destroy()

特性说明：

二、扩展实现方案

1. Web Audio API（高级音频处理）

// 创建音频上下文
const audioContext = new (window.AudioContext || window.webkitAudioContext)()

// 加载音频文件
fetch('/static/audio/beep.mp3')
  .then(res => res.arrayBuffer())
  .then(buffer => audioContext.decodeAudioData(buffer))
  .then(decodedData => {
    // 创建音频源
    const source = audioContext.createBufferSource()
    source.buffer = decodedData
    
    // 创建效果器（示例：增益节点）
    const gainNode = audioContext.createGain()
    gainNode.gain.value = 0.5
    
    // 连接节点
    source.connect(gainNode)
    gainNode.connect(audioContext.destination)
    
    // 播放控制
    source.start(0)
    source.stop(audioContext.currentTime + 2) // 2秒后停止
  })

适用场景：

• 需要音频可视化
• 实时音效处理（如变声、混响）
• 精确音频时间控制

2. 第三方音频库（Howler.js）

// 安装依赖
npm install howler

// 在 Vue 中使用
import { Howl } from 'howler'

const sound = new Howl({
  src: ['/static/audio/beep.mp3'],
  html5: true,
  volume: 0.8,
  onend: () => console.log('播放结束')
})

// 播放控制
sound.play()
sound.pause()
sound.stop()

优势对比：

3. H5+ Audio 模块（App 端增强）

// 获取音频管理对象
const audio = plus.audio.createPlayer('/static/audio/beep.mp3')

// 高级配置
audio.setSessionCategory('playback') // 设置音频会话模式
audio.setRoute('speaker') // 强制扬声器输出

// 播放控制
audio.play(() => console.log('播放成功'), (err) => console.error(err))

特有功能：

• 蓝牙设备控制
• 耳机插拔检测
• 声道平衡调节
• 音频焦点管理

三、最佳实践方案

1. 音频预加载策略

// 创建预加载队列
const preloadList = [
  { id: 'beep', src: '/static/audio/beep.mp3' },
  { id: 'success', src: '/static/audio/success.mp3' }
]

// 使用 Map 存储实例
const audioMap = new Map()

preloadList.forEach(item => {
  const audio = uni.createInnerAudioContext()
  audio.src = item.src
  audio.autoplay = false
  audioMap.set(item.id, audio)
})

2. 自动播放兼容方案

// 用户交互后初始化音频
document.addEventListener('click', initAudio, { once: true })

function initAudio() {
  const audio = uni.createInnerAudioContext()
  audio.src = '/static/audio/beep.mp3'
  
  // 提前加载但不播放
  audio.play()
  audio.pause()
}

3. 性能优化方案

// Web Worker 处理音频解码
const worker = new Worker('/workers/audio-decoder.js')

worker.postMessage({
  audioData: arrayBuffer,
  format: 'mp3'
})

worker.onmessage = (e) => {
  const decodedData = e.data
  // 使用解码后的音频数据
}

// audio-decoder.js 内容：
self.onmessage = function(e) {
  const { audioData, format } = e.data
  // 使用合适的解码库处理
  const decoded = decodeAudio(audioData, format)
  self.postMessage(decoded)
}

四、常见问题处理

1. 微信小程序音频限制

// 必须使用 wx.downloadFile 下载音频文件
wx.downloadFile({
  url: 'https://example.com/audio.mp3',
  success(res) {
    const audio = wx.createInnerAudioContext()
    audio.src = res.tempFilePath
    audio.play()
  }
})

2. 自动播放策略规避

<!-- 添加 muted 属性实现自动播放 -->
<audio id="bgm" muted controls>
  <source src="bgm.mp3" type="audio/mpeg">
</audio>

<script>
document.addEventListener('click', () => {
  const audio = document.getElementById('bgm')
  audio.muted = false
  audio.play()
})
</script>

3. 内存泄漏预防

// 创建对象池
const audioPool = []

function getAudio() {
  return audioPool.pop() || uni.createInnerAudioContext()
}

function releaseAudio(audio) {
  audio.stop()
  audio.offPlay()
  audio.offError()
  audioPool.push(audio)
}