更新记录

1.0.0（2026-09-24） 下载此版本

zxj-audio-player 是一个面向 uni-app Vue2/Vue3 App 项目的 UTS 原生音频播放插件。它解决的是“后端已经把 MP3、M4A 等音频内容用 Base64 返回了，前端怎样稳定播放”的问题：调用方无需自己把 Base64 转临时文件、区分 Android 与 iOS 播放器，也不必维护两套原生代码。

平台兼容性

uni-app(5.0)

zxj-audio-player

将 Base64 音频写入 App 私有缓存，再交给 Android/iOS 原生播放器播放。适合在线 TTS、接口返回音频流、离线语音包等场景。

zxj-audio-player 是一个面向 uni-app Vue2/Vue3 App 项目的 UTS 原生音频播放插件。它解决的是“后端已经把 MP3、M4A 等音频内容用 Base64 返回了，前端怎样稳定播放”的问题：调用方无需自己把 Base64 转临时文件、区分 Android 与 iOS 播放器，也不必维护两套原生代码。

检索关键词： uni-app 音频播放、UTS 音频插件、Base64 播放 MP3、Base64 播放 M4A、TTS 语音播报、文字转语音播放、Android MediaPlayer、iOS AVAudioPlayer、App 原生音频播放器、uni-app AI 语音。

适用场景

• AI 助手、智能客服、导航播报返回的 TTS Base64 音频。
• 接口直接返回音频二进制内容，业务层已转换为 Base64。
• 需要在 Android 和 iOS App 中用一套 JavaScript API 播放提示音、语音讲解或课程音频。
• 希望播放前落到 App 私有缓存，避免业务层处理临时路径的项目。

如果你的音频是公开 URL、需要播放列表、倍速、后台控制中心或锁屏控制，建议优先使用 uni.createInnerAudioContext 或专门的媒体播放方案；本插件专注于 Base64 音频流落盘后的单条播放。

支持平台

• Android（minSdk 21）
• iOS（iOS 12+）

支持 uni-app Vue2、Vue3 的 App 端构建；不支持 H5 与各类小程序。H5/小程序可在业务层按平台条件编译，使用对应平台的标准音频 API。

它是怎么工作的

1. JavaScript 侧传入不带 Data URL 头的 Base64 字符串和文件名。
2. UTS 原生层解码数据，并写入应用缓存目录，不申请公共存储权限。
3. Android 用 MediaPlayer 异步准备并播放；iOS 用 AVAudioPlayer 播放。
4. 播放结束时执行 success；出错时通过 fail 返回统一错误码。

每次调用 playAudioFromBase64 都会先停止当前播放，适合语音播报“后来的内容覆盖前面的内容”的产品逻辑。

使用方法

import {
  isAudioPlaying,
  playAudioFromBase64,
  stopAudioPlayback,
} from '@/uni_modules/zxj-audio-player'

playAudioFromBase64({
  base64: audioBase64.replace(/^data:audio\/[^;]+;base64,/, ''),
  fileName: 'speech.mp3',
  success: ({ filePath }) => {
    console.log('播放完成，缓存文件：', filePath)
  },
  fail: (error) => {
    uni.showToast({ title: error.errMsg, icon: 'none' })
  },
})

isAudioPlaying({
  success: ({ playing }) => console.log('是否正在播放：', playing),
})

stopAudioPlayback({})

API 一览

playAudioFromBase64 的 fileName 建议保留真实扩展名，例如 answer.mp3 或 notice.m4a，这样原生播放器更容易识别格式。

注意事项

• base64 请传纯 Base64，不要携带 data:audio/...;base64, 前缀。
• success 在音频自然播放完成时触发；如需判断播放状态，请调用 isAudioPlaying。
• 新一次播放会停止上一次播放。音频缓存位于应用私有目录，系统可在空间紧张时清理它。
• Base64 很大时会占用额外内存与缓存空间，长音频、课程音频更适合改用 URL 播放或分片下载。
• 插件不会上传、分析或持久化音频内容；音频只在设备缓存目录中短暂存在。

常见问题

为什么传入 data:audio/mp3;base64, 后播放失败？

插件接口接收的是纯 Base64。请在业务层先移除逗号前的 Data URL 前缀，示例代码已包含这一处理。

success 为什么不是刚调用就触发？

该回调用来表示自然播放完成。要即时更新界面，可以在调用后更新“加载中/播放中”状态，再用 isAudioPlaying 查询实际播放状态。

是否需要申请录音或存储权限？

不需要。插件只读取传入的字符串并写入 App 私有缓存，不访问麦克风，也不写入公共下载目录。

错误码