简介这是一份基于uniapp框架编写的录音播放功能源码专门面向在小程序端实现类似微信按住说话交互的开发者。整个资源以一个Vue单文件作为核心演示从按下录音、松开停止并保存的完整流程即使不依赖完整工程也能独立提取出语音消息模块的关键逻辑在录音侧通过启动录音接口和停止录音接口控制采集利用录音状态监听实时获取已录制时长并处理异常在播放侧则通过播放接口及结束回调完成语音回放同时结合触摸按下和离开事件模拟按住说话手势。代码还给出了录音管理器的使用思路能够进行采样率、声道等高级配置并介绍录音文件保存与读取的方法方便持久化语音数据。压缩包内仅包含1个vue文件大小约1KB体量非常轻结构清晰适合有一定基础的开发者直接阅读并嵌入自身工程该资源已有5794人学习下载对于实现语音聊天、语音留言等功能具有直接参考价值也是理解uniapp多端录音播放差异的实用示例。1. uniapp实现录音播放不是拿来即用为什么多数Demo在你的真机上会翻车我第一次接这个需求时想法很朴素官方给了录音 API 和播放 API一个按录制、一个按播放撑死半天就能交付。可真机一跑就发现Demo 和工程是两回事iOS 上录完的音频时长跟服务端统计总对不上安卓上同一段录音播放时而有声时而没声H5 端在部分浏览器里连麦克风权限都拿不到。所谓“uniapp实现录音、播放功能”背后是一条完整的链路——权限申请、录音管理器、音频编码、文件生命周期、播放器状态机以及三端差异适配。这篇文章会把链路拆开从选型到代码、从参数到避坑目标是让新手能照着落一个“小程序端、App 端、H5 端都真实可用”的录音加播放最小工程而不是只跑通一个页面。2. 录音链路拆解从麦克风权限到拿到可用音频文件2.1 录音管理器选型getRecorderManager() 与原生插件的边界uniapp 官方给出的录音入口是uni.getRecorderManager()它返回一个全局唯一的 RecorderManager 实例。这个封装在小程序端由宿主平台提供底层录音能力在 App 端由运行时的原生模块实现在 H5 端则适配浏览器的 MediaRecorder。对“录音-上传-回放”这类常见业务这套封装已经够用了。真正要作出判断的场景是你需要实时音量检测、边录边转文字、多轨混音或者退到后台还要继续录。官方封装在这些场景下会露出边界——没有音波级回调、无法干预编码器内部状态、后台录音会被系统策略打断。我通常的做法是先把官方方案跑通整条流程再按需求逐项排查是否触发官方 API 的能力上限确认触发之后才考虑引入原生插件或 App 端的 plus 能力补充。不要一上来就搞双链路否则维护成本会直接翻倍。选型时还有一点容易忽略RecorderManager 是单例整个应用只有一个实例。如果你在每个页面都调用一次uni.getRecorderManager()并挂自己的回调后挂的监听会把前面的覆盖掉事件会错乱。工程化的做法是单独建一个工具模块把实例持有在模块里回调也只挂一次页面只负责发起开始和停止。// recorder.js let recorderSingleton null function getRecorder() { if (recorderSingleton) return recorderSingleton recorderSingleton uni.getRecorderManager() // 回调只挂一次避免多页面反复注册导致事件覆盖 recorderSingleton.onError((err) { console.error(录音出错:, err) }) return recorderSingleton } export function startRecord(options) { const recorder getRecorder() recorder.start({ duration: 60000, // 最长录 60 秒超时自动停止 sampleRate: 16000, // 16k 采样率语音场景够用文件更小 numberOfChannels: 1, // 单声道避免双声道文件多出一倍体积 format: aac, // 小程序端与 App 端兼容性最好 bitrate: 48 // 48kbps日常录音清晰度与体积的折中 }) } export function stopRecord() { getRecorder().stop() // onStop 回调里返回 tempFilePath、duration、fileSize }这段代码的要点有四个。第一getRecorder()用了模块级缓存保证整个应用生命周期只持有一个 RecorderManager 实例。第二duration设置了 60 秒上限一到时间系统会自动停止并触发 onStop业务侧不用自己写超时器。第三sampleRate我一般不在正式环境用 4410016k 对人声录音足够文件体积能小一半以上。第四bitrate对应码率塞得太低会有明显电流声太高会让上传变慢48kbps 是语音留言类场景的常见折中。这里要专门提醒format参数不是你想要什么后端就能收什么它受到端能力限制。小程序端在部分安卓机型上对 mp3 支持不佳混用 iOS 和安卓时 aac 的兼容面最稳。真要统一消费 mp3建议在后端转码而不是在端上强行统一格式。2.2 录音参数逐项拆解format、sampleRate、numberOfChannels 与码率的取舍参数虽然在上一段代码里写了但直接抄参数容易踩坑因为不同端的默认值和对参数的处理方式不一样。我习惯拉一张表对照方便你根据项目情况调整。参数我常用的值可选范围选择理由与坑formataacaac / mp3aac 在 App 端和小程序端表现最稳定mp3 在部分安卓机型上会录出 0 字节文件sampleRate16000 / 441008000~44100纯人声 16k 足够做音频分析或音乐识别再用 44100体积会大不少numberOfChannels11 / 2录音留言用单声道双声道只在你明确需要立体声时选bitrate48~968~160码率低于 32 噪声明显高于 128 在语音场景里听不出收益duration60000最大 600000不传则使用系统上限容易出现用户忘记停止导致超长文件采样率这里经常有新手踩坑想省空间就把 sampleRate 调成 8000结果播放端听起来像蒙着被子说话。手机麦克风的硬件采样率大多高于 8k强行降采样并不会省下多少体积反而增加转码损耗。语音类业务推荐 16k 起步这是听感和文件大小的性价比拐点。numberOfChannels和bitrate是一对变相的体积开关。单声道、16k 采样率、48kbps 码率一分钟语音大约 360KB双声道、44.1k 采样率、128kbps 码率一分钟能到 1MB 左右。对需要频繁上传的 IM 类业务这是体量级的差距。反过来如果你录的是教学讲解、会议纪要需要保留较宽频响就可以升到 44100 和 128kbps。2.3 最小可运行录音代码从按下到拿到文件路径理论说完落到页面上。录音通常是“按下开始、松开停止”或“点击录制、再点停止”两种交互这里以第二种为例写最小闭环。// pages/record/index.vue节选 import { startRecord, stopRecord } from /utils/recorder.js data() { return { recording: false, tempFilePath: , duration: 0 } }, methods: { toggleRecord() { if (!this.recording) { this.recording true startRecord() } else { stopRecord() } } }但这段代码少了一块录音停止后怎么拿到文件。单纯调 stop 不会自动回传路径必须预先注册 onStop 回调。很多初学者把 onStop 写在页面里结果每次进入页面都重复注册事件越积越多。更稳妥的方式是在模块初始化阶段只注册一次 onStop把结果通过回调队列分发出去。// recorder.js 改进版 let recorderSingleton null let stopCallbacks [] function ensureRecorder() { if (recorderSingleton) return recorderSingleton recorderSingleton uni.getRecorderManager() recorderSingleton.onStop((res) { stopCallbacks.forEach((cb) cb(res)) stopCallbacks [] }) recorderSingleton.onError((err) { console.error(录音出错:, err) stopCallbacks [] }) return recorderSingleton } export function startRecord(options, onStopCallback) { const recorder ensureRecorder() if (typeof onStopCallback function) { stopCallbacks.push(onStopCallback) } recorder.start({ ...defaultOptions, ...options }) } export function stopRecord() { ensureRecorder().stop() }这样每次调用 startRecord 时传入的 onStop 回调会进入一个队列recorder 的 onStop 事件统一分发页面卸载后也不会出现回调空跑。页面侧只需要关心停止后拿到的 tempFilePath 和 duration 两个字段。// 页面侧使用 startRecord({}, (res) { this.tempFilePath res.tempFilePath this.duration res.duration this.recording false })这里的核心逻辑是点击时根据当前状态决定 start 或 stop录音结束后在 onStop 回调里取到文件路径与时长后续的播放、上传都依赖这两个值。到这里录音链路的最小闭环已经成立。3. 播放链路拆解兼容小程序端、App 端与 H5 端的播放实现3.1 播放器选型InnerAudioContext 何时够用、何时必须换方案播放这一侧uniapp 官方提供uni.createInnerAudioContext()返回一个 InnerAudioContext 实例。这个实例同时支持远程 URL 和本地文件路径自带播放、暂停、停止、跳转进度、倍速、音量控制等基础能力。绝大多数项目里录完音立即回放、从服务器拉取历史录音来播放它都能覆盖不需要额外引播放器插件。什么时候必须换方案有两个典型信号。一是你需要音频波形可视化InnerAudioContext 拿不到实时 PCM 数据只能在播放前由后端或本地解析出波形点阵。二是你需要后台播放、锁屏控制栏、耳机线控这类“媒体会话”级能力这套上下文对象在 App 端达不到原生播放器的完整度。对于第一种我会引入音频解码插件或由服务端预生成波形对于第二种App 端要换原生插件小程序端只能用宿主平台的能力上限H5 端则走 HTML5 Audio 加 Media Session API。所以播放器选型的原则和录音类似能跑通业务的直接用官方对象卡在具体能力上再换。提前换通常意味着失去跨端一致性也提前引入额外的体积和维护成本。3.2 播放控制进度回调、倍速播放与录音自动回放InnerAudioContext 的事件命名和 Web Audio 的惯例接近onTimeUpdate 提供播放位置更新onEnded 触发自然播放结束onError 在出问题时触发。下面这一段是“录音成功后立即回放”的典型实现function playRecord(tempFilePath) { const audio uni.createInnerAudioContext() audio.src tempFilePath audio.startTime 0 // 从 0 秒开始播放 audio.play() audio.onTimeUpdate((res) { // res.currentTime 单位是秒可以做进度条 progress.value res.currentTime }) audio.onEnded(() { progress.value audio.duration audio.destroy() // 播放结束及时释放 }) audio.onError((err) { console.error(播放错误:, err) uni.showToast({ title: 播放失败, icon: none }) audio.destroy() }) return audio }关键点有两个。第一不要在每次播放时都 new 一个 InnerAudioContext 又不管它这样会在页面切换时叠加多个活动音频形成声音重叠甚至卡死每次实例用完都要显式调用destroy()。第二onEnded 里也必须 destroy因为音频对象持有底层资源不释放会造成内存持续增长长时间使用后表现就是找不到原因的黑匣子式卡顿。如果需要倍速播放直接在实例上设置audio.speed 1.5 // 支持范围 0.5 - 2.0倍速设置在大部分 App 端和 H5 端是生效的但我见过某些安卓机型对低于 1 的倍速支持不完整表现为声音变调。真机测试时必须用 0.75、1.5、2.0 三个倍速各播一段确认变调问题后再上线。3.3 播放结束与异常处理onEnded、onError 与资源释放播放器的生命周期必须主动管理。不少开发者只写了 onPlay 就开始调 play忽略了 onEnded 和 onError 的资源释放导致页面退后台后声音还在响或者再次进入页面时能听到上一段录音的尾巴。我一般把播放器封成模块统一控制生命周期。// audioPlayer.js let currentAudio null export function playAudio(src) { destroyCurrentAudio() // 先释放上一个实例 currentAudio uni.createInnerAudioContext() currentAudio.src src currentAudio.onError(() { console.error(播放出错:, src) destroyCurrentAudio() }) currentAudio.onEnded(() { destroyCurrentAudio() }) currentAudio.play() return currentAudio } export function stopAudio() { if (!currentAudio) return currentAudio.stop() destroyCurrentAudio() } function destroyCurrentAudio() { if (!currentAudio) return currentAudio.destroy() currentAudio null }这里有三个必须注意的边界。一每次 play 前都要 destroy 上一次的实例否则快节奏操作下会有多个音频实例同时活跃表现出来就是两个声音叠在一起。二播放远程 URL 时onError 的触发比本地文件频繁得多网络差、服务端没配跨域、音频格式未知都会走到这里一定要有降级提示。三不要在小程序端调用audio.stop()之后不 destroystop 只是暂停在当前状态资源仍然占着。4. 录音文件管理临时路径、本地持久化与服务端上传4.1 文件路径机制临时文件会过期别把 tempFilePath 当永久资产onStop 回调返回的tempFilePath是本次录音生成的临时文件路径这个文件在短时间内有效应用重启、缓存清理、系统压力大时可能被直接回收。你不能只把这个路径存进数据库就完事下次打开页面用这个路径去播放大概率会扑空。正确的处理方式有两种。本地需要长期保留的用uni.saveFile把它存为持久文件需要跨端共享的直接uni.uploadFile传到服务器拿到 URL 以后再存。对录音功能来说通常两种都要做先本地保存一份做回放再异步上传一份做多端同步。function saveAndUpload(tempFilePath) { return new Promise((resolve, reject) { // 1. 本地保存为持久文件 uni.saveFile({ tempFilePath, success: (saveRes) { const savedFilePath saveRes.savedFilePath // 2. 上传到服务端 uni.uploadFile({ url: https://api.example.com/audio/upload, filePath: savedFilePath, name: file, success: (uploadRes) { const serverUrl JSON.parse(uploadRes.data).url resolve({ savedFilePath, serverUrl }) }, fail: reject }) }, fail: reject }) }) }注意uni.saveFile在小程序端有总大小限制几十兆的录音文件很容易触发保存失败App 端的保存行为在不同版本上也不完全一致。我一般会再加一层降级保存失败的场景至少先把 tempFilePath 存在内存变量里等上传成功后重新生成音频链接不再依赖本地持久文件。上传的细节也不容忽视name字段对应服务端接收的文件字段名iOS 上临时文件没有扩展名的情况很常见上传时要用formData额外携带格式信息服务端才能正确判断文件类型。4.2 上传录音文件uni.uploadFile 与服务端的格式约定如果只是把文件丢给后端不约定格式你可能收到一堆后缀名乱写的文件。录音文件至少要有三个约定字段名、编码格式、采样信息。实践里我会让后端同事在接口文档里明确请求字段file接收音频文件Content-Type由 uniapp 自动处理不需要前端设置请求体里的format、sampleRate、numberOfChannels三个业务字段必须同时提交后端才能正确转码、剪辑和生成预览。下面是一个标准请求结构uni.uploadFile({ url: https://api.example.com/audio/upload, filePath: tempFilePath, name: file, formData: { format: aac, sampleRate: 16000, channels: 1, duration: this.duration }, success: (res) { // res.data 是服务端返回的 JSON 字符串 const resp JSON.parse(res.data) uni.setStorageSync(audio_${this.recordId}, resp.url) } })服务端收到文件后最好做三件事用音频探测工具读取真实编码格式校验文件大小和时长是否和 formData 写的一致不一致就按真实值落库。我在模拟项目X里被“前端传时长、后端按前端时长另存”的坑坑过一次前端采样率 16k后端播放器却按 44.1k 去解码导致播放时长估算和实际不一致。后来统一以后端工具解析出的真实值为准问题才消失。4.3 录音列表展示与缓存清理策略如果项目里有“录音历史”列表需要为每条录音保存以下字段id、savedFilePath、serverUrl、duration、format、createTime。列表展示时优先用 serverUrl因为跨端播放在本地路径上存在很多例外只有离线场景才回退到 savedFilePath。// 录音条目对象 const recordItem { id: unique_id, savedFilePath: , serverUrl: https://cdn.example.com/audio/xxx.aac, duration: 58000, format: aac, createTime: 1720000000000 }缓存清理是老生常谈但经常没人做。录音文件通常单个只有几百 KB但用户量一上来、录音次数一多本地缓存也会膨胀到上百 MB。建议的策略是录音上传成功后本地保存的文件仅保留最近 30 天超期的在应用启动或列表页加载时用uni.getSavedFileList列出后逐个按时间删除。这个策略在小程序端尤其重要因为本地文件有上限不清就会导致后续录音保存失败。5. 录音播放避坑实录真机上翻车的 7 个常见问题5.1 iOS 上录音时长统计与回调值不一致现象录音完成onStop 回调里 duration 是 58 秒但服务端拿到文件后解析出的时长是 56 秒播放器按 56 秒播放却又在后 2 秒出现空白。 原因onStop 返回的 duration 是宿主系统估算的录音时长包含开始和结束的缓冲并不等于编码文件的真实播放时长。 解决以服务端解析出的真实时长为准播放进度条同样以加载后的 audio.duration 为准不要拿 onStop 的 duration 直接渲染进度。5.2 App 端录音文件播放失败编码与路径源不一致现象同样的录音逻辑小程序端一切正常App 端点击播放无声音控制台也没报错。 原因App 端的底层录音实现与播放器实现是不同原生模块录出的文件在个别路径形态下被播放器拒绝。 解决在 App 端先对 tempFilePath 做存在性校验确认文件存在后再交给播放器仍然失败时尝试先复制到应用私有目录再播。把文件路径归一化为应用私有目录下的绝对路径后问题概率会大幅下降。// 校验文件是否可访问的跨段写法 try { if (typeof uni.getFileSystemManager function) { uni.getFileSystemManager().accessSync(filePath) } // App 端可加 plus.io 的兜底校验 } catch (e) { console.error(文件不可访问:, filePath) }5.3 权限被拒后回调不触发现象用户首次拒绝麦克风权限后再次点击录音按钮页面没有任何反应也没有 error 事件。 原因部分端在权限被拒时不会触发 RecorderManager 的 onError而是直接不响应 start 调用。 解决在调用录音前先通过uni.getSetting检查授权状态未授权时先引导而不是直接调 start。uni.getSetting({ success: (res) { if (!res.authSetting[scope.record]) { // 弹窗说明用途引导去设置页 return } startRecord() } })5.4 播放器对象重复创建导致声音重叠现象用户连点两次播放按钮听到两个声音同时播放或者从播放页返回列表页声音还在响。 原因多个 InnerAudioContext 实例没有被销毁旧实例的播放没有停止。 解决全局只保留一个播放器实例每次 play 前先destroy()旧的再重建或复用。destroy 之后把引用置空防止后续调用空对象方法。5.5 H5 端录音经常不可用现象H5 端点击录音按钮浏览器弹出麦克风权限询问用户点了允许但录音时长始终为 0或完全没反应。 原因浏览器要求页面运行在 HTTPS 环境且音频采集必须由用户手势触发部分浏览器还要求页面处于聚焦状态才能调用采集设备。 解决H5 端统一走 HTTPS录音按钮首次点击时创建音频上下文后续点击复用在移动端内置浏览器和桌面浏览器上分别做验证。5.6 后台录音被系统掐断现象录音过程中切到后台再切回来发现录音早就停了onStop 也没触发。 原因移动系统出于省电和隐私考虑限制后台麦克风占用。 解决把后台录音明确为不支持边界在录音开始前提示用户保持应用在前台。目前主流端能力都不支持无限后台录音与其硬做不如在产品上规避。5.7 录音文件过大导致上传超时现象录了 3 分钟文件 3MB上传到第 65% 时请求失败。 原因移动网络不稳定上传大文件容易出现超时或连接重置。 解决录音时控制码率和时长上传失败时提供重试按钮或改用分片上传。对超大文件服务端提供断点续传接口前端不要硬扛。6. 进阶验证从“能响”到“好用”6.1 全链路闭环录制到播放到上传到回放验证法功能做到“能响”只是第一步真正上线前要建立一套闭环验证流程。我的习惯是每轮测试都按固定顺序人工走一遍开始录音、停止录音、本地立即回放、保存本地文件、上传服务端、从服务端回放、删除本地文件、重新拉取服务器地址回放。每步都要记录格式、时长、大小、路径来源和播放结果任何一步异常都回到上一节对应的避坑项排查。这个闭环的价值在于把问题隔离录错是编码问题本地播不出是路径问题上传后播不出是服务端或跨域问题。没有这个顺序你很难定位是哪个环节出的问题经常会在页面代码里反复改一些无关变量。6.2 不同端音频格式相容性矩阵我建议在验收阶段做一张三端格式矩阵表固定录音参数后分别验证各格式在三端的表现。验证端录音格式播放本地文件播放服务端文件实际结论小程序端aac通过通过可作为默认格式App 端 iOSaac通过通过无特殊处理App 端安卓aac需先做路径校验通过需路径归一化H5 端aac部分浏览器不支持通过需要降级策略除了矩阵表我习惯在项目里保留一个“音频能力自测页面”列出当前设备支持哪些格式、哪些操作方便更换测试设备后快速排查兼容性。这个页面代码量不大但能在三端联调时省下大量来回沟通的时间。在音频功能这个方向上我更推荐先把交互收敛为“录音、立即回放、上传”三层尽量别在前期引入边录边传、实时变调、后台录音这些边界能力等基础链路足够稳定再逐项加。这个顺序能帮你少走很多弯路也减少大量刚上线就翻车之后的赶工补丁。上一轮某项目最后线上出问题的不是录音本身而是用户录了 10 分钟长文件上传失败后没有重试入口——这类问题要在第一版设计时就预留位置。跨端音频功能尤其如此端差异带来的翻车场景远比想象中多。希望这一套链路拆解和踩坑记录能帮你在自己项目里少花几个夜晚排查玄学问题也让录音、播放真正做到三端一致、心中有数。希望帮到你。本文还有配套的精品资源点击获取