简介面向Flutter开发者的录音功能实现资源包基于flutter-sound与flutter-sound-record封装适用于iOS、Android及Web端快速集成录音能力可支撑语音备忘录、课堂录音、社交通讯等常见场景对初学者与中级开发者均友好。压缩包共2000个文件大小约769MB文件类型涵盖Dart核心逻辑、XML与Properties系统配置、JSON数据、Markdown开发说明、Java/Objective-C原生桥接代码另含Web插件注册与音频播放辅助模块工程结构清晰完整便于按模块查阅。已有2148人学习下载。资源附带可运行的完整工程覆盖录音器初始化、音频编码格式与比特率/采样率设置、开始与停止录音、保存路径以及Android/iOS麦克风权限配置等核心环节支持WAV、MP3、AAC等常见格式并演示录音状态管理、文件保存与音频播放衔接可直接参考集成或二次修改。配合audio player与插件注册文件可进一步理解跨端音频处理与依赖注入方式帮助梳理Flutter原生通信与插件工程组织逻辑适合有一定Flutter基础、希望快速落地录音功能的开发者。 做Flutter项目遇到录音功能第一反应肯定是在pub.dev上翻插件。我当初就是这么入坑的翻了半天发现录音相关的库其实就那几个record、flutter_sound、audio_streamer还有个老牌的recorder。实话说能把录音这件事做得完整、文档又不太离谱的flutter_sound算一个。而标题里说的flutter_sound-record其实就是flutter_sound库里负责录音这一块的模块。这篇文章我不打算给你抄一段官方文档就算完事而是把我从集成到上线整个过程中遇到的问题、参数怎么调、坑踩在哪里全部捋一遍。不管你是刚开始接触Flutter录音还是已经集成到一半卡住了这篇内容应该都能帮上忙。1. 项目概述与方案选型1.1 需求场景与核心痛点先说说我手里的项目场景。当时做的是一个语音笔记类App用户需要短按录音、松手停止然后上传到服务端转文字。需求听起来很简单但真正落地的时候涉及的问题一点都不少权限申请、音频会话管理、录音格式选择、文件保存路径、录音时长回调、后台时录音会不会被系统打断、Android和iOS两端的权限逻辑差异这些如果不提前想清楚后面改起来非常痛苦。我在技术选型时对比了以下几个方案直接用原生平台通道MethodChannel写原生录音再通过Flutter调用。使用社区录音库record。使用flutter_sound包含flutter_sound_record与flutter_sound_play。使用audio_streamer自己处理音频流。直接写原生通道的好处是完全可控但坏处是两边代码量都不小而且音频焦点处理、生命周期管理这些逻辑要自己维护维护成本不低。record库使用起来确实简单但功能上偏轻量想要精细控制编码器、采样率、音量回调、后台录音会有点力不从心。audio_streamer更多面向实时音频流处理场景和普通录音需求不太匹配。最终我选了flutter_sound主要原因是它内部封装了录音和播放两套完整能力对Android的AudioRecord和MediaRecorder、iOS的AVAudioRecorder/AVAudioPlayer都有比较好的抽象而且支持丰富的编码格式和流式回调。最关键的是它支持在录音过程中拿到分贝数据做录音波形动画很顺手这对语音笔记类场景是刚需。1.2 版本选择与兼容性注意flutter_sound目前版本已经迭代了很多轮比如9.x。选定这个库之后面临的第一个头疼问题就是版本兼容。Flutter本身的版本如果不和插件版本对齐很容易出现依赖解析失败。我当时的Flutter版本是3.x使用flutter_sound的9.x版本没问题。这里特别提醒一句如果你用的是很老的Flutter版本比如2.x就不要强行上9.x否则编译的时候会报一堆莫名其妙的错——不是你代码写错了而是API签名变了。优先去pub.dev上看插件官方声明的Flutter SDK最低版本要求老老实实对上再说。另外flutter_sound在9.x版本之后录音和播放功能的API结构做过调整FlutterSoundRecorder这个类被拆到flutter_sound_record模块下你需要分开导入。刚开始集成的时候很多人还按老博客的写法import package:flutter_sound/flutter_sound.dart;结果发现类找不到。在新版本里需要像下面这样引入import package:flutter_sound_record/flutter_sound_record.dart;这个看似很小的细节卡了我不少时间。2. 环境准备与依赖配置2.1 依赖安装与版本锁定在pubspec.yaml里添加依赖时我建议你锁定一个具体的版本号而不是直接写^9.2.0这样带脱字符的宽松版本。原因很简单flutter_sound每次小版本升级都有可能调整原生依赖稍不注意就拉出一个新版本导致本机编译需要重新拉取资源还可能出现依赖冲突。我当时锁定的版本是dependencies: flutter_sound: ^9.2.13添加完依赖后在项目根目录执行flutter pub get如果在国内网络环境下依赖包拉不下来是很常见的问题。不止flutter_sound很多插件在首次拉取的时候都会卡住。这时候可以在项目根目录或者全局Flutter配置里加镜像源用国内可访问的Flutter镜像这样下载依赖会顺畅很多。还有个小技巧如果某个插件依赖一直拉不下来先看看是不是因为缺少某个传递依赖比如path_provider这类基础库先把基础库的版本对齐再回来加flutter_sound很多时候问题就解决了。顺便说一句很多GitHub上star数很高的Flutter项目其实内部都封装了flutter_sound。如果你不想从零开始写直接找个成熟的开源录音App项目把它的录音服务层代码拿过来看比自己摸索API快得多。但要注意不同项目的封装方式差别很大代码能不能直接套用还是要看你自己的业务场景——比如你只是录个音发到聊天消息里那就不需要把整个波形录制组件都搬过来。2.2 平台权限与构建配置权限这块Android和iOS两边都要做漏一个都会导致录音静默失败。Android端在android/app/src/main/AndroidManifest.xml中添加录音权限uses-permission android:nameandroid.permission.RECORD_AUDIO /如果你的App需要保存录音到外部存储还需要加上存储权限Android 11以上建议使用媒体库方式具体看你App的targetSdk版本。除了权限声明Android 6.0以上还需要在运行时动态申请权限flutter_sound本身不处理权限申请你需要用permission_handler这个插件在调用录音前发起请求否则直接调用startRecorder你会发现它静默失败或者根本不会弹出授权框。iOS端在ios/Runner/Info.plist中添加keyNSMicrophoneUsageDescription/key string需要使用麦克风录制语音内容/string如果不添加这个描述调用录音初始化时App会直接崩溃而且崩溃日志不会很明确你很容易误认为是代码逻辑问题实际上就是一个描述字符串缺失。另外在模拟器上测试时麦克风权限会让很多人一脸懵。模拟器默认会弹权限框但它使用的可能是Mac电脑的麦克风或者干脆就是无声源。建议录音相关功能一定要真机自测模拟器只能用来验证UI布局和基本逻辑。构建配置还有一个容易踩的坑Flutter 3.x之后对Gradle插件的应用方式做了调整如果你在项目里用老写法直接applyFlutter的Gradle插件构建时会看到类似“You are applying Flutters main Gradle plugin imperatively using the apply script method”的警告。这个警告不影响普通项目运行但如果你同时改了Gradle版本就可能导致构建失败。稳妥的做法是按照Flutter新版模板改用插件声明方式配置settings.gradle和build.gradle避免老写法与新Gradle版本不兼容。3. 核心API解析与录音流程实现3.1 录音会话初始化FlutterSoundRecorder用起来的第一步不是直接调startRecorder()而是要先打开音频会话。这一步很多新手会忽略导致后面所有操作都没反应。录音器初始化大致是这样的流程final recorder FlutterSoundRecorder(); Futurevoid initRecorder() async { await recorder.openAudioSession(); await recorder.setAudioSource(AudioSource.microphone); }openAudioSession()用来创建一个音频会话在iOS上会对应AVAudioSession的激活在Android上会创建AudioRecord并准备好音频焦点。如果你不调用这个方法直接录音大概率会得到一个底层错误。setAudioSource()是用来指定音频源的默认就是麦克风但显式设置一次可以避免某些机型上的默认值差异。如果你做的是通话场景可能需要设置为voiceCommunication它会启用回声消除和降噪录制效果会明显不同。3.2 录音开始与停止的完整流程录音开始很简单但有几个参数值得认真说await recorder.startRecorder( toFile: filePath, codec: Codec.aacLc, bitRate: 128000, sampleRate: 44100, numChannels: 1, );toFile录音保存的完整文件路径注意是路径和文件名组合不能只传文件名。codec编码格式常用aacLc兼顾音质和文件体积。bitRate码率语音类128kbps足够音乐类建议192kbps以上。sampleRate采样率语音识别类服务建议16000或44100看你的后续处理需求。numChannels声道数语音笔记一般单声道就够文件也更小。停止录音时需要用stopRecorder()并确保把录音器的会话释放掉await recorder.stopRecorder(); await recorder.closeAudioSession();我见过不少人忘记调用closeAudioSession()导致再次进页面录音时麦克风无响应。因为在iOS上音频会话没有被正确释放时前一次录音占用的资源还挂着新一次录音就开不起来。为了稳妥我封装了一个录音服务类里面用枚举管理当前状态防止用户在录音过程中疯狂点击按钮导致状态错乱bool _isRecording false; Futurevoid toggleRecording() async { if (_isRecording) { await stopAndSave(); } else { await startNewRecording(); } }状态管理这件事在录音功能里非常重要。录音不是瞬时操作用户可能在不同页面间切换如果没有一个全局的录音状态很容易出现“上一个页面录着音下一个页面又来一次startRecorder”这种低级但致命的bug。3.3 录音参数与格式选择的经验flutter_sound_record对编码格式的支持是它的一大优势但支持多不代表每个都要懂这里分享我实测下来的一套经验编码格式文件体积音质适用场景aacLc较小良好通用录音推荐opus最小良好网络传输、聊天语音pcm16很大最好音频分析、波形显示、后期处理aacHE小一般低比特率语音场景我最终选择aacLc是因为文件大小和音质比较均衡而且服务端转文字时兼容性好。如果你的App有语音识别需求建议先确认服务商支持什么编码格式别录音录完发现服务端不能解析。采样率方面如果你录制的是语音16000是一个很常见的选项很多语音识别API默认接受16kHz单声道的PCM或压流格式。如果既要录音又要播放44100更通用。还有一个冷门但实用的API——录音过程中的分贝回调。flutter_sound支持在录音同时监听分贝变化recorder.onProgress?.listen((data) { // data.duration 录音时长 // data.decibels 分贝值范围一般在-160到0之间 });这个回调可以做录音波形动画也可以用来判断说话音量是否过低是一个非常实用的扩展点。我当初做“说话太轻”的提示功能就依赖这个回调。4. 常见问题与排查技巧实录4.1 权限弹窗不出现或录制后无声这个问题我遇到的次数最多而且原因也各不相同。情况一iOS没有权限描述表现是点击录音按钮后App直接崩溃。解决办法就是在Info.plist里补上NSMicrophoneUsageDescription这个前面已经提过。情况二Android权限已授予但startRecorder报错这种情况多半是音频焦点被占用。比如你在录音的同时系统正在播放音乐或者另一款App占用了麦克风AudioRecord初始化就会失败。解决办法是录音开始前使用audio_focus插件获取音频焦点或者至少监听焦点变化并在失去焦点时自动停止录音。情况三权限都正常录音文件也有但播放没有声音这其实不是麦克风的问题而是文件路径不对或者录音没有写入到文件中。toFile参数如果传了一个不存在的目录Android端可能会静默失败但iOS端会直接抛异常。建议录音前先确保父目录已创建final dir await getApplicationDocumentsDirectory(); final filePath ${dir.path}/voice_${DateTime.now().millisecondsSinceEpoch}.m4a;4.2 Gradle构建报错与依赖下载失败集成时如果遇到Gradle相关问题大概率是Flutter版本和Gradle版本不匹配。我自己遇到过的报错包括“You are applying Flutters main Gradle plugin imperatively using the apply script method…”这属于Flutter模板更新后项目里的android/build.gradle没有同步更新导致的。解决办法是在settings.gradle中正确引入Flutter插件并将build.gradle中的应用方式改成插件声明式。依赖下载卡死或超时这种情况几乎都出在首次拉取或网络环境不稳的场景。除了配置国内镜像源还可以删除pub缓存后重新flutter pub get。如果某一两个具体包拉不下来少用版本脱字符把版本写死能有效减少解析时长。报错提示找不到flutter_sound中的某个类大概率是版本不统一。比如你项目里某个其他插件依赖了一个老版本的flutter_sound而你在pubspec.yaml里写的是新版本实际编译时会冲突。检查一下pubspec.lock确认一下解析出来的版本和代码里用的API是否一致。4.3 录音时长与后台状态处理录音过程中用户按Home键退回桌面或者切到其他App录音会不会中断这是语音类App必须处理的问题。受系统限制Android上MediaRecorder在App退到后台时通常可以继续录制但iOS上默认不支持后台录音你需要在Info.plist中声明UIBackgroundModes并包含audio一行。keyUIBackgroundModes/key array stringaudio/string /array但要注意这个配置提交App Store审核时苹果会询问后台音频的实际使用场景。如果你的App并没有后台播放需求只为了录音去声明存在审核被拒的风险。我当时的处理方式是录音时如果检测到App进入后台自动加一条系统通知提示用户“录音仍在进行中”这样既满足合规要求又不会因为长时间静默后台录音导致被系统杀死。录音时长限制也建议做成可配置的。flutter_sound没有内置最大时长限制你需要在onProgress回调里自己判断时长并停止录音。我当时设置了一个5分钟上限到时间自动保存并通知用户这比让用户无限录下去要稳妥得多。4.4 小技巧录音后立即播放的坑录音停止后如果你立刻用一个FlutterSoundPlayer去播放同一个文件偶尔会遇到打不开的情况尤其是刚写完文件就马上播放。这个问题的根源是文件句柄尚未完全释放。解决方法是停止录音后等待约300毫秒再初始化播放器await recorder.stopRecorder(); await Future.delayed(const Duration(milliseconds: 300)); await player.startPlayer(fromFile: filePath);你别小看这300毫秒它能省掉你一堆“明明文件存在却播放失败”的排查时间。再补充一点录音文件尽量不要和临时文件混放在一起。我在项目里单独建了一个records目录每个用户的录音按日期分文件夹存放后面调试定位问题时特别方便。5. 延伸思考与个人体会录音功能从表面看就是一个startRecorder和stopRecorder的事情真正做透了才发现这里面牵扯的东西太多平台权限策略的差异、音频会话的生命周期、文件存储策略、后台任务处理、编码格式兼容、播放端的联动……每一个点都能写一篇专项文章。flutter_sound这个库帮我节省了大量底层工作但也不能完全依赖它尤其在做跨平台App时Android真机和iOS真机上的行为差异一定要尽早测试。我自己吃过亏的地方是在Android上跑得好好的录音格式到iOS上文件播放正常但时长对不上最后排查发现是采样率和声道设置不一致导致的。所以换平台必测录音换格式必测播放这两个动作千万别省。如果你打算在自己的项目里集成录音我最后再分享一个实用建议不要一上来就把录音功能封装成一个巨大的插件先用最简单的方式把“录音→存文件→播放”这条链路跑通然后再逐步加波形、加水印、加上传、加后台录音。链路越短出问题时越好定位。等基础跑通了再去折腾高级功能你会觉得顺很多。本文还有配套的精品资源点击获取