简介微信小程序绘本跟读案例源码是一份面向小程序开发者和移动开发学习者的完整示例项目适用于想了解教育类应用中语音交互实现方式的人群。资源包共100个文件以60个png图片、11个json配置、10个js逻辑、9个wxss样式、8个wxml页面结构为主并附带1个zip与1个ts文件整体仅1.87MB轻量易下载。案例围绕“绘本跟读”展开整合了录音播放、语音识别、文本比对与评分等核心流程覆盖了小程序页面结构搭建、数据绑定、事件处理、生命周期管理、API调用与状态管理。通过研读源码开发者可以掌握微信开发者工具使用、常见API如wx.startRecord与wx.getRecorderManager的调用并学习异步处理、错误反馈及性能优化等实操经验直接借鉴到自己的教育类小程序开发中。目前已有969人学习下载值得作为从入门到进阶的参考资料。1. 拿到绘本跟读案例源码.zip先想清楚这条音频链路解压这个案例压缩包时如果只把注意力放在“哪个文件是首页”上大概率会在跑demo时把大量时间耗在音频不播、进度不对、录音没声这类问题上。“绘本跟读”不是一个阅读器加一个录音按钮而是播放、录音、高亮、评分四件事共享同一条“句子时间轴”绘本里的每一页有若干句子每句话有对应的音频片段和文字位置跟读时用户按下按钮录音录音结束后把音频交出去评测再把分数和原句回显到界面上。这类案例源码真正可复用的资产不是某张页面长什么样而是围绕这条时间轴的工程边界数据怎么建、播放状态怎么管、录音和播放怎么互斥、评分接口怎么替换。这篇文章就顺着这套链路拆开讲适合正在做儿童教育、语言学习类微信小程序的开发者也适合刚接手微信小程序项目实例、想从案例里抽出可复用代码的人。2. 案例工程的目录结构与绘本书籍数据建模拿到源码的第一步不是读代码而是先分清这套工程是“微信原生小程序”还是“uniapp微信小程序”因为两者不仅目录结构不同组件通信和生命周期处理也有差异。后面的所有代码示例都按原生小程序结构给出uniapp 工程只需要把data换掉、事件换成$emit即可。2.1 先分清“原生小程序”还是“uniapp 工程”最常见的判断方式是在解压后先看根目录有没有app.json。原生小程序的根目录就是小程序代码根的源头app.json、app.js、pages/一目了然而 uniapp 工程根目录是src/或pages.json且pages.json里字段风格偏 JSON 配置而非小程序原生。特征原生小程序uniapp 微信小程序入口文件app.json / app.jssrc/main.js编译后生成 app.json页面目录pages/ 下直接放 .wxml/.wxss/.js/.jsonpages/ 下放 .vue编译后才生成 wx 文件组件写法Component({ ... })Vue 单文件组件事件通信triggerEvent / bind:tap$emit / tap案例源码位置直接引用即可需要先npm run build:mp-weixin再导入开发者工具拿到 zip 后先做一次“体检”看project.config.json里的miniprogramRoot字段如果指向的是dist/build/mp-weixin这就是 uniapp 产物。这种工程直接改源码没用要在 HBuilderX 里打开src目录重新构建。还有一个细节原生小程序的app.json里会有permission字段去声明scope.record用途uniapp 工程则在manifest.json的mp-weixin节点里配。2.2 绘本的“页、句、热区”三层数据结构跟读类小程序里一本书的数据通常不是“图片加一排按钮”而是按页拆句子、按句子拆热区。我一般会在utils/book-data.js里维护一个纯数据对象方便单独测试。下面这段结构可以看作绘本案例源码里最核心的骨架const book { id: little-red-hat, name: 小红帽, cover: /static/books/little-red-hat/cover.jpg, // 每一页绘本图片 该页所有句子 pages: [ { id: p1, bg: /static/books/little-red-hat/p1.jpg, // 每句话文本、音频起止秒、文字在页面上的位置 sentences: [ { id: s1, text: Once upon a time, there was a little girl., audio: /static/books/little-red-hat/s1.mp3, start: 0, // 这句在整段音频里的开始秒 end: 5.2, // 结束秒 // 文字区域用于点击点读 hotspot: { x: 40, y: 560, width: 280, height: 120 } } ] } ] };这段数据有几个值得注意的设计决定。第一start和end用数字秒而非hh:mm:ss字符串因为audioCtx.seek()和onTimeUpdate回调拿到的都是秒存字符串就意味着每次都要解析。第二整本书共用一个语句音频目录每句独立一个 mp3 文件这样切页时不需要重新加载大文件内存占用更低。第三hotspot存的是x/y/width/height这四个值对应绘本背景图上的相对坐标区间渲染时再根据当前屏幕宽度做等比换算。字段类型作用容易踩的坑pages[].bgString背景图地址不要用云文件临时链接真机上会失效sentences[].audioString单句音频需要放到静态资源目录或配置合法域名sentences[].start/endNumber音频起止秒必须与音频实际长度一致否则高亮空转sentences[].hotspotObject点击区域坐标与背景图宽高不是等比时会导致点不准2.3 用组件拆分“阅读页”的几个状态阅读页是绘本跟读的主战场页面状态至少有“播放中”“录音中”“评测中”“空闲”四种。如果全部写在页面里代码会迅速膨胀。常见做法是把“热区句子”抽成子组件子组件只负责展示文字和高亮状态播放控制交给父组件统一管理。// components/sentence-line/sentence-line.js Component({ properties: { text: String, active: Boolean, // 当前是否是正在播放/高亮的句子 state: String // idle | playing | recording | scoring }, methods: { onTap() { // 只上报事件不直接操作音频 this.triggerEvent(select, { id: this.data.id }); } } });!-- components/sentence-line/index.wxml -- view classsentence {{active ? active : }} bind:taponTap text classstate-tag{{stateText}}/text text{{text}}/text /view父页面持有book和currentIndex子组件通过active属性感知自己是否应该高亮。要注意的是子组件内部不要自己去wx.createInnerAudioContext()否则每个句子组件都创建一个音频实例切页时容易造成多个声音同时播放且很难回收。事件全部用triggerEvent抛给页面页面在handleSentenceSelect里统一决定是重播当前句还是切换句子。// pages/reader/index.js Page({ data: { book: null, currentPageIndex: 0, currentSentenceIndex: 0, audioState: idle }, onLoad() { this.setData({ book: getBookData() }); }, handleSentenceSelect(e) { const { id } e.detail; // 找到 id 对应的句下标重启播放 this.playSentenceById(id); } });这样的好处是后续如果要加入“上一句/下一句”按钮只需要在页面上把currentSentenceIndex做增减再调用同一个播放方法不需要改组件。案例源码里如果出现this.selectComponent(.xxx).play()这种写法建议改成统一事件驱动否则组件层级一多状态同步会非常困难。3. 音频播放与翻页同步InnerAudioContext 的用法与坑播放是跟读的基础。微信小程序里没有 HTML 的Audio对象只有wx.createInnerAudioContext()创建出来的实例它有play/pause/stop/seek等方法和onTimeUpdate/onEnded/onError等回调。真正做起来容易翻车的点是翻页、循环、自动断句这些“节目逻辑”而不是单纯调接口。3.1 初始化一个“不踩交互”的播放实例全局只保留一个音频实例放在app.js里挂到globalData上所有页面共用它。不要在页面里反复创建也不要销毁后再新建。// app.js 或一个单独的 audio-manager.js const audioCtx wx.createInnerAudioContext(); audioCtx.obeyMuteSwitch false; // iOS 上允许后台播放控制 audioCtx.autoplay false; wx.setInnerAudioOption({ mixWithOther: true, // 允许与其他音频混播录音前需处理 obeyMuteSwitch: false });obeyMuteSwitch的作用比较隐蔽iOS 用户的手机侧边静音键默认会让小程序音频“不响”很多用户反馈“有声音啊但没动静”其实就是这个开关没设成false。mixWithOther则关系到后面录音模块如果一直为false录音时播放器会在 iOS 上被系统切走导致录出来的人声忽大忽小。建议默认都按上面这段配置。3.2 翻页、seek、自动断句的协同每句音频独立文件翻页和“下一句”本质上都是切换audioCtx.src并重新play()。难点在于自动断句当前句子播完后自动进下一句以及用户手动点别句子时要立刻打断当前播放。function playSentence(pageIndex, sentenceIndex) { const page currentBook.pages[pageIndex]; const sentence page.sentences[sentenceIndex]; // 先清掉旧的事件回调防止 onEnded 连续触发 audioCtx.offEnded(); audioCtx.src sentence.audio; audioCtx.startTime 0; audioCtx.play(); audioCtx.onEnded(() { // 自动下一句 const nextIndex sentenceIndex 1; if (nextIndex page.sentences.length) { playSentence(pageIndex, nextIndex); } else { setPageFinished(pageIndex); } }); }这段代码里有三个值得讲清楚的点。第一每次播放前先offEnded()否则上一次播放的onEnded回调还会残留出现“点第一句播完却跳到第三句”的错乱。第二案例对象里如果每句音频对应整页音频的片段可以只加载整页音频一次用audioCtx.seek(sentence.start)定位到句子开头到sentence.end时暂停。第三页面离开时要调用audioCtx.stop()而不是pause()pause()会保留 src 但也会保留播放位置容易导致回来时从奇怪的位置续播。更严格的方式是在onHide里pause()并记录currentPositiononShow时根据状态恢复。onTimeUpdate的触发频率大约每 250ms 一次不要在里面做复杂计算只更新一个时间戳字段。更常见的方案是在onTimeUpdate里判断“当前时间超过句子 end 则自动 next”但交给onEnded更稳因为onEnded是在音频完整播放完才触发不容易被节流或卡顿影响。3.3 播放状态机与异常兜底跟读场景比单纯阅读多一个“录音状态”如果用一个布尔变量到处判断很容易出现“播放着点录音录音里又点了播放”的交错。建议用枚举字符串做状态机const STATE { IDLE: idle, PLAYING: playing, RECORDING: recording, SCORING: scoring };每次操作前先检查当前状态只允许合法迁移PLAYING可以到RECORDING但RECORDING时不能直接play()必须先stopRecord()再切状态。这比依赖wx.getRecorderManager().stop()的异步回调可控得多。错误码常见原因处理建议-101音频文件不存在或路径错误检查 src 路径区分绝对路径与相对路径-102网络加载失败确认域名已配入合法域-103音频格式不支持统一转成 mp3 或 aac不要用 ogg/wav-105解码失败常见 Android换转码工具重新导出一份音频源文件尽量用工具批量转成 44.1kHz、128kbps 的 mp3最大程度减少 Android 真机上的解码问题。案例里如果出现audioCtx.onError回调至少要在回调里把audioState置回IDLE否则界面会一直停留在加载中用户只能杀进程。4. 跟读录音评测从麦克风权限到结果展示的一个闭环跟读的“读”依赖录音。这一章直接把完整闭环写出来录音前处理、录音参数、上传评测、结果展示。4.1 录音前先停掉播放音频如果录音的同时音频还在放iOS 上经常出现“录进的是自己朗读声和原句混在一起”或“原句突然变小”的问题。原生录音器一旦start()系统会接管音频会话所以录音前一定要先暂停或停掉当前播放器。function startRecord() { // 先记录播放状态录音结束后恢复 const shouldResume audioCtx.paused false; audioCtx.pause(); wx.authorize({ scope: scope.record, success() { beginRecord(); }, fail() { // 用户拒绝后第二次进入需引导跳设置页 wx.showModal({ title: 需要麦克风权限, content: 请在设置中允许使用麦克风, success() { wx.openSetting(); } }); } }); }这段代码的细节在于wx.authorize只在小程序第一次请求时弹窗有效如果用户之前拒绝过再次调用会直接走fail。此时不能用wx.authorize死磕而是应该引导用户到wx.openSetting手动打开。录音中的状态机切换也放在这里audioState从PLAYING切到RECORDING界面上隐藏播放按钮显示“正在录音”。4.2 录音参数与上传录音管理器wx.getRecorderManager()是整个小程序的单例和InnerAudioContext一样不要每次录音都重新创建。const recorder wx.getRecorderManager(); recorder.start({ duration: 30000, // 最长 30 秒 sampleRate: 16000, // 16kHz 满足语音评测需要 numberOfChannels: 1, // 单声道体积更小 encodeBitRate: 48000, // 16kHz 采样率建议配 48kbps format: mp3 // iOS 和 Android 都支持 }); recorder.onStop((res) { const tempFilePath res.tempFilePath; uploadRecord(tempFilePath); });参数建议值说明duration30000跟读通常一句不超过 30 秒sampleRate16000语音评测接口普遍接受 16k 或 48knumberOfChannels1双声道对人声识别无意义且增大体积formatmp3兼容性优于 pcm/wav上传更小上传用wx.uploadFile这个是常规操作但要注意两点tempFilePath在微信小程序里只保证当前冷启动周期内有效如果需要留档应该先wx.saveFile把临时文件转成本地文件上传时必须带name字段让后端能使用常规的 multipart 方式读到文件。function uploadRecord(filePath) { wx.uploadFile({ url: https://api.example.com/evaluate, filePath, name: audio, formData: { bookId: currentBook.id, sentenceId: currentSentence.id }, timeout: 15000, success(res) { const result JSON.parse(res.data); showScore(result.score); }, fail(err) { // 保底显示重试按钮不要直接让用户干等 } }); }timeout默认是 60 秒这招很坑后端接口如果一直不返回前端会傻等一分钟。语音评测本身耗时不高15 秒足够了。另外在success里拿到的是字符串类型的res.data必须手动JSON.parse后再访问字段。4.3 评测分数的“前端展示”与“服务端真评”真实生产环境里跟读评测一般由服务端对接第三方语音评测引擎讯飞、腾讯云等小程序端只管录音上传和结果展示。但案例源码为了可独立运行通常会在前端内置一个“模拟评分”根据录音时长占原句音频时长的比例、原句长度等经验公式算个分数。function mockScore(recordDuration, sentenceDuration, textLength) { let score 95; // 时长偏差每多 15%扣 5 分 const diff Math.abs(recordDuration - sentenceDuration) / sentenceDuration; if (diff 0.1) score - 10; if (diff 0.25) score - 15; // 句子长完整读出的难度高给一点补偿 if (textLength 20) score 3; return Math.max(0, Math.min(100, Math.round(score))); }这套模拟逻辑的价值在于让整套 UI 流程先完整跑通不阻塞开发。但它没有任何“语音内容比对”能力读错词也能拿高分。上线前一定要替换成服务端评测并且前端应对自己拿到的score字段做类型校验避免后端返回null时页面渲染直接崩掉。方式耗时成本适用阶段前端模拟分0ms无开发期、UI 联调服务端真评1~3s按调用量计费生产环境4.4 真机 vs 模拟器录音功能验证清单微信开发者工具里的录音功能可以“跑通”但不可信。模拟器用的是电脑麦克风音频格式、采样率和服务端不兼容的情况很多。真正验证时按下表逐项过一遍验证项模拟器Android 真机iOS 真机权限弹窗部分版本不弹正常正常录音后试听无声或延迟正常正常播放与录音混播不表现为系统级冲突正常需要 mixWithOther上传后后端解析可能格式坏正常正常如果出现“模拟器上录完上传成功后端解析失败”先别怀疑代码换真机重测即可定位。另外录音时如果页面有长列表滚动注意在scroll-view的touchstart里做一次recorder.stop()的节流防止用户滑动时误触录音键导致疯狂生成文件。5. 给“跟读”加上逐词高亮用时间戳校准音频与文案很多绘本案例做到句子级别高亮就结束了但用户打开绘本类小程序期望是“读到哪个词哪个词亮起来”。这属于进阶玩法但实现成本其实很低核心是给每个词补上时间戳。5.1 数据里带上词级时间轴在前面sentences数据的基础上给每个句子增加一个words数组。如果绘本音频本身没有词级时间戳常见做法是按整句时长对每个字符做均分function buildWords(sentence, text, audioDuration) { const chars text.split(); const unit audioDuration / chars.length; return chars.map((char, i) { return { text: char, start: Number((i * unit).toFixed(2)), end: Number(((i 1) * unit).toFixed(2)) }; }); }这个均分方案对有明显停顿的句子会有几十毫秒误差但视觉上无伤大雅。如果后续接入了带音素级别的评测结果可以把服务端返回的每个词对齐时间替换掉这里的估算值。5.2 用 onTimeUpdate 驱动渲染而不是 setTimeout逐词高亮最容易写错的地方是有人用setTimeout模拟一句歌词滚动一旦用户手动 seek 或网络卡顿setTimeout的时间线就和真实播放进度脱节。正确做法是在onTimeUpdate里根据当前播放位置计算词下标audioCtx.onTimeUpdate(() { const pos audioCtx.currentTime; // 秒 let wordIndex 0; const words currentSentence.words; for (let i 0; i words.length; i) { if (pos words[i].start pos words[i].end) { wordIndex i; break; } } if (wordIndex ! this.data.currentWordIndex) { this.setData({ currentWordIndex: wordIndex }); } });这里还有一个常被忽略的性能细节onTimeUpdate每 250ms 触发一次但setData在小程序里是昂贵的操作。上面的代码先比较wordIndex是否变化再setData避免高频重复渲染同一份数据。对于 30 个字以内的句子这个量级的更新完全没问题如果以后要做整页长文本逐词高亮还需要升级成 WXS 响应式方案将高亮计算下放到渲染层彻底脱离setData的负担。验证这套时间轴是否对齐的办法很简单在页面上临时放一个调试文本直接显示currentTime、currentWordIndex和当前词的起止秒用真机播放后观察一旦某个句子“音画同步”但下一句偏移 200ms 以上问题一定出在音频文件剪裁上而不是代码。把start/end从句子级扩展到词级、再从词级扩展到拼音级这套时间轴数据模型就足以支撑点读、跟读、口语评测三种功能同时存在。本文还有配套的精品资源点击获取
微信小程序绘本跟读案例源码拆解：音频链路与录音评测实战
简介微信小程序绘本跟读案例源码是一份面向小程序开发者和移动开发学习者的完整示例项目适用于想了解教育类应用中语音交互实现方式的人群。资源包共100个文件以60个png图片、11个json配置、10个js逻辑、9个wxss样式、8个wxml页面结构为主并附带1个zip与1个ts文件整体仅1.87MB轻量易下载。案例围绕“绘本跟读”展开整合了录音播放、语音识别、文本比对与评分等核心流程覆盖了小程序页面结构搭建、数据绑定、事件处理、生命周期管理、API调用与状态管理。通过研读源码开发者可以掌握微信开发者工具使用、常见API如wx.startRecord与wx.getRecorderManager的调用并学习异步处理、错误反馈及性能优化等实操经验直接借鉴到自己的教育类小程序开发中。目前已有969人学习下载值得作为从入门到进阶的参考资料。1. 拿到绘本跟读案例源码.zip先想清楚这条音频链路解压这个案例压缩包时如果只把注意力放在“哪个文件是首页”上大概率会在跑demo时把大量时间耗在音频不播、进度不对、录音没声这类问题上。“绘本跟读”不是一个阅读器加一个录音按钮而是播放、录音、高亮、评分四件事共享同一条“句子时间轴”绘本里的每一页有若干句子每句话有对应的音频片段和文字位置跟读时用户按下按钮录音录音结束后把音频交出去评测再把分数和原句回显到界面上。这类案例源码真正可复用的资产不是某张页面长什么样而是围绕这条时间轴的工程边界数据怎么建、播放状态怎么管、录音和播放怎么互斥、评分接口怎么替换。这篇文章就顺着这套链路拆开讲适合正在做儿童教育、语言学习类微信小程序的开发者也适合刚接手微信小程序项目实例、想从案例里抽出可复用代码的人。2. 案例工程的目录结构与绘本书籍数据建模拿到源码的第一步不是读代码而是先分清这套工程是“微信原生小程序”还是“uniapp微信小程序”因为两者不仅目录结构不同组件通信和生命周期处理也有差异。后面的所有代码示例都按原生小程序结构给出uniapp 工程只需要把data换掉、事件换成$emit即可。2.1 先分清“原生小程序”还是“uniapp 工程”最常见的判断方式是在解压后先看根目录有没有app.json。原生小程序的根目录就是小程序代码根的源头app.json、app.js、pages/一目了然而 uniapp 工程根目录是src/或pages.json且pages.json里字段风格偏 JSON 配置而非小程序原生。特征原生小程序uniapp 微信小程序入口文件app.json / app.jssrc/main.js编译后生成 app.json页面目录pages/ 下直接放 .wxml/.wxss/.js/.jsonpages/ 下放 .vue编译后才生成 wx 文件组件写法Component({ ... })Vue 单文件组件事件通信triggerEvent / bind:tap$emit / tap案例源码位置直接引用即可需要先npm run build:mp-weixin再导入开发者工具拿到 zip 后先做一次“体检”看project.config.json里的miniprogramRoot字段如果指向的是dist/build/mp-weixin这就是 uniapp 产物。这种工程直接改源码没用要在 HBuilderX 里打开src目录重新构建。还有一个细节原生小程序的app.json里会有permission字段去声明scope.record用途uniapp 工程则在manifest.json的mp-weixin节点里配。2.2 绘本的“页、句、热区”三层数据结构跟读类小程序里一本书的数据通常不是“图片加一排按钮”而是按页拆句子、按句子拆热区。我一般会在utils/book-data.js里维护一个纯数据对象方便单独测试。下面这段结构可以看作绘本案例源码里最核心的骨架const book { id: little-red-hat, name: 小红帽, cover: /static/books/little-red-hat/cover.jpg, // 每一页绘本图片 该页所有句子 pages: [ { id: p1, bg: /static/books/little-red-hat/p1.jpg, // 每句话文本、音频起止秒、文字在页面上的位置 sentences: [ { id: s1, text: Once upon a time, there was a little girl., audio: /static/books/little-red-hat/s1.mp3, start: 0, // 这句在整段音频里的开始秒 end: 5.2, // 结束秒 // 文字区域用于点击点读 hotspot: { x: 40, y: 560, width: 280, height: 120 } } ] } ] };这段数据有几个值得注意的设计决定。第一start和end用数字秒而非hh:mm:ss字符串因为audioCtx.seek()和onTimeUpdate回调拿到的都是秒存字符串就意味着每次都要解析。第二整本书共用一个语句音频目录每句独立一个 mp3 文件这样切页时不需要重新加载大文件内存占用更低。第三hotspot存的是x/y/width/height这四个值对应绘本背景图上的相对坐标区间渲染时再根据当前屏幕宽度做等比换算。字段类型作用容易踩的坑pages[].bgString背景图地址不要用云文件临时链接真机上会失效sentences[].audioString单句音频需要放到静态资源目录或配置合法域名sentences[].start/endNumber音频起止秒必须与音频实际长度一致否则高亮空转sentences[].hotspotObject点击区域坐标与背景图宽高不是等比时会导致点不准2.3 用组件拆分“阅读页”的几个状态阅读页是绘本跟读的主战场页面状态至少有“播放中”“录音中”“评测中”“空闲”四种。如果全部写在页面里代码会迅速膨胀。常见做法是把“热区句子”抽成子组件子组件只负责展示文字和高亮状态播放控制交给父组件统一管理。// components/sentence-line/sentence-line.js Component({ properties: { text: String, active: Boolean, // 当前是否是正在播放/高亮的句子 state: String // idle | playing | recording | scoring }, methods: { onTap() { // 只上报事件不直接操作音频 this.triggerEvent(select, { id: this.data.id }); } } });!-- components/sentence-line/index.wxml -- view classsentence {{active ? active : }} bind:taponTap text classstate-tag{{stateText}}/text text{{text}}/text /view父页面持有book和currentIndex子组件通过active属性感知自己是否应该高亮。要注意的是子组件内部不要自己去wx.createInnerAudioContext()否则每个句子组件都创建一个音频实例切页时容易造成多个声音同时播放且很难回收。事件全部用triggerEvent抛给页面页面在handleSentenceSelect里统一决定是重播当前句还是切换句子。// pages/reader/index.js Page({ data: { book: null, currentPageIndex: 0, currentSentenceIndex: 0, audioState: idle }, onLoad() { this.setData({ book: getBookData() }); }, handleSentenceSelect(e) { const { id } e.detail; // 找到 id 对应的句下标重启播放 this.playSentenceById(id); } });这样的好处是后续如果要加入“上一句/下一句”按钮只需要在页面上把currentSentenceIndex做增减再调用同一个播放方法不需要改组件。案例源码里如果出现this.selectComponent(.xxx).play()这种写法建议改成统一事件驱动否则组件层级一多状态同步会非常困难。3. 音频播放与翻页同步InnerAudioContext 的用法与坑播放是跟读的基础。微信小程序里没有 HTML 的Audio对象只有wx.createInnerAudioContext()创建出来的实例它有play/pause/stop/seek等方法和onTimeUpdate/onEnded/onError等回调。真正做起来容易翻车的点是翻页、循环、自动断句这些“节目逻辑”而不是单纯调接口。3.1 初始化一个“不踩交互”的播放实例全局只保留一个音频实例放在app.js里挂到globalData上所有页面共用它。不要在页面里反复创建也不要销毁后再新建。// app.js 或一个单独的 audio-manager.js const audioCtx wx.createInnerAudioContext(); audioCtx.obeyMuteSwitch false; // iOS 上允许后台播放控制 audioCtx.autoplay false; wx.setInnerAudioOption({ mixWithOther: true, // 允许与其他音频混播录音前需处理 obeyMuteSwitch: false });obeyMuteSwitch的作用比较隐蔽iOS 用户的手机侧边静音键默认会让小程序音频“不响”很多用户反馈“有声音啊但没动静”其实就是这个开关没设成false。mixWithOther则关系到后面录音模块如果一直为false录音时播放器会在 iOS 上被系统切走导致录出来的人声忽大忽小。建议默认都按上面这段配置。3.2 翻页、seek、自动断句的协同每句音频独立文件翻页和“下一句”本质上都是切换audioCtx.src并重新play()。难点在于自动断句当前句子播完后自动进下一句以及用户手动点别句子时要立刻打断当前播放。function playSentence(pageIndex, sentenceIndex) { const page currentBook.pages[pageIndex]; const sentence page.sentences[sentenceIndex]; // 先清掉旧的事件回调防止 onEnded 连续触发 audioCtx.offEnded(); audioCtx.src sentence.audio; audioCtx.startTime 0; audioCtx.play(); audioCtx.onEnded(() { // 自动下一句 const nextIndex sentenceIndex 1; if (nextIndex page.sentences.length) { playSentence(pageIndex, nextIndex); } else { setPageFinished(pageIndex); } }); }这段代码里有三个值得讲清楚的点。第一每次播放前先offEnded()否则上一次播放的onEnded回调还会残留出现“点第一句播完却跳到第三句”的错乱。第二案例对象里如果每句音频对应整页音频的片段可以只加载整页音频一次用audioCtx.seek(sentence.start)定位到句子开头到sentence.end时暂停。第三页面离开时要调用audioCtx.stop()而不是pause()pause()会保留 src 但也会保留播放位置容易导致回来时从奇怪的位置续播。更严格的方式是在onHide里pause()并记录currentPositiononShow时根据状态恢复。onTimeUpdate的触发频率大约每 250ms 一次不要在里面做复杂计算只更新一个时间戳字段。更常见的方案是在onTimeUpdate里判断“当前时间超过句子 end 则自动 next”但交给onEnded更稳因为onEnded是在音频完整播放完才触发不容易被节流或卡顿影响。3.3 播放状态机与异常兜底跟读场景比单纯阅读多一个“录音状态”如果用一个布尔变量到处判断很容易出现“播放着点录音录音里又点了播放”的交错。建议用枚举字符串做状态机const STATE { IDLE: idle, PLAYING: playing, RECORDING: recording, SCORING: scoring };每次操作前先检查当前状态只允许合法迁移PLAYING可以到RECORDING但RECORDING时不能直接play()必须先stopRecord()再切状态。这比依赖wx.getRecorderManager().stop()的异步回调可控得多。错误码常见原因处理建议-101音频文件不存在或路径错误检查 src 路径区分绝对路径与相对路径-102网络加载失败确认域名已配入合法域-103音频格式不支持统一转成 mp3 或 aac不要用 ogg/wav-105解码失败常见 Android换转码工具重新导出一份音频源文件尽量用工具批量转成 44.1kHz、128kbps 的 mp3最大程度减少 Android 真机上的解码问题。案例里如果出现audioCtx.onError回调至少要在回调里把audioState置回IDLE否则界面会一直停留在加载中用户只能杀进程。4. 跟读录音评测从麦克风权限到结果展示的一个闭环跟读的“读”依赖录音。这一章直接把完整闭环写出来录音前处理、录音参数、上传评测、结果展示。4.1 录音前先停掉播放音频如果录音的同时音频还在放iOS 上经常出现“录进的是自己朗读声和原句混在一起”或“原句突然变小”的问题。原生录音器一旦start()系统会接管音频会话所以录音前一定要先暂停或停掉当前播放器。function startRecord() { // 先记录播放状态录音结束后恢复 const shouldResume audioCtx.paused false; audioCtx.pause(); wx.authorize({ scope: scope.record, success() { beginRecord(); }, fail() { // 用户拒绝后第二次进入需引导跳设置页 wx.showModal({ title: 需要麦克风权限, content: 请在设置中允许使用麦克风, success() { wx.openSetting(); } }); } }); }这段代码的细节在于wx.authorize只在小程序第一次请求时弹窗有效如果用户之前拒绝过再次调用会直接走fail。此时不能用wx.authorize死磕而是应该引导用户到wx.openSetting手动打开。录音中的状态机切换也放在这里audioState从PLAYING切到RECORDING界面上隐藏播放按钮显示“正在录音”。4.2 录音参数与上传录音管理器wx.getRecorderManager()是整个小程序的单例和InnerAudioContext一样不要每次录音都重新创建。const recorder wx.getRecorderManager(); recorder.start({ duration: 30000, // 最长 30 秒 sampleRate: 16000, // 16kHz 满足语音评测需要 numberOfChannels: 1, // 单声道体积更小 encodeBitRate: 48000, // 16kHz 采样率建议配 48kbps format: mp3 // iOS 和 Android 都支持 }); recorder.onStop((res) { const tempFilePath res.tempFilePath; uploadRecord(tempFilePath); });参数建议值说明duration30000跟读通常一句不超过 30 秒sampleRate16000语音评测接口普遍接受 16k 或 48knumberOfChannels1双声道对人声识别无意义且增大体积formatmp3兼容性优于 pcm/wav上传更小上传用wx.uploadFile这个是常规操作但要注意两点tempFilePath在微信小程序里只保证当前冷启动周期内有效如果需要留档应该先wx.saveFile把临时文件转成本地文件上传时必须带name字段让后端能使用常规的 multipart 方式读到文件。function uploadRecord(filePath) { wx.uploadFile({ url: https://api.example.com/evaluate, filePath, name: audio, formData: { bookId: currentBook.id, sentenceId: currentSentence.id }, timeout: 15000, success(res) { const result JSON.parse(res.data); showScore(result.score); }, fail(err) { // 保底显示重试按钮不要直接让用户干等 } }); }timeout默认是 60 秒这招很坑后端接口如果一直不返回前端会傻等一分钟。语音评测本身耗时不高15 秒足够了。另外在success里拿到的是字符串类型的res.data必须手动JSON.parse后再访问字段。4.3 评测分数的“前端展示”与“服务端真评”真实生产环境里跟读评测一般由服务端对接第三方语音评测引擎讯飞、腾讯云等小程序端只管录音上传和结果展示。但案例源码为了可独立运行通常会在前端内置一个“模拟评分”根据录音时长占原句音频时长的比例、原句长度等经验公式算个分数。function mockScore(recordDuration, sentenceDuration, textLength) { let score 95; // 时长偏差每多 15%扣 5 分 const diff Math.abs(recordDuration - sentenceDuration) / sentenceDuration; if (diff 0.1) score - 10; if (diff 0.25) score - 15; // 句子长完整读出的难度高给一点补偿 if (textLength 20) score 3; return Math.max(0, Math.min(100, Math.round(score))); }这套模拟逻辑的价值在于让整套 UI 流程先完整跑通不阻塞开发。但它没有任何“语音内容比对”能力读错词也能拿高分。上线前一定要替换成服务端评测并且前端应对自己拿到的score字段做类型校验避免后端返回null时页面渲染直接崩掉。方式耗时成本适用阶段前端模拟分0ms无开发期、UI 联调服务端真评1~3s按调用量计费生产环境4.4 真机 vs 模拟器录音功能验证清单微信开发者工具里的录音功能可以“跑通”但不可信。模拟器用的是电脑麦克风音频格式、采样率和服务端不兼容的情况很多。真正验证时按下表逐项过一遍验证项模拟器Android 真机iOS 真机权限弹窗部分版本不弹正常正常录音后试听无声或延迟正常正常播放与录音混播不表现为系统级冲突正常需要 mixWithOther上传后后端解析可能格式坏正常正常如果出现“模拟器上录完上传成功后端解析失败”先别怀疑代码换真机重测即可定位。另外录音时如果页面有长列表滚动注意在scroll-view的touchstart里做一次recorder.stop()的节流防止用户滑动时误触录音键导致疯狂生成文件。5. 给“跟读”加上逐词高亮用时间戳校准音频与文案很多绘本案例做到句子级别高亮就结束了但用户打开绘本类小程序期望是“读到哪个词哪个词亮起来”。这属于进阶玩法但实现成本其实很低核心是给每个词补上时间戳。5.1 数据里带上词级时间轴在前面sentences数据的基础上给每个句子增加一个words数组。如果绘本音频本身没有词级时间戳常见做法是按整句时长对每个字符做均分function buildWords(sentence, text, audioDuration) { const chars text.split(); const unit audioDuration / chars.length; return chars.map((char, i) { return { text: char, start: Number((i * unit).toFixed(2)), end: Number(((i 1) * unit).toFixed(2)) }; }); }这个均分方案对有明显停顿的句子会有几十毫秒误差但视觉上无伤大雅。如果后续接入了带音素级别的评测结果可以把服务端返回的每个词对齐时间替换掉这里的估算值。5.2 用 onTimeUpdate 驱动渲染而不是 setTimeout逐词高亮最容易写错的地方是有人用setTimeout模拟一句歌词滚动一旦用户手动 seek 或网络卡顿setTimeout的时间线就和真实播放进度脱节。正确做法是在onTimeUpdate里根据当前播放位置计算词下标audioCtx.onTimeUpdate(() { const pos audioCtx.currentTime; // 秒 let wordIndex 0; const words currentSentence.words; for (let i 0; i words.length; i) { if (pos words[i].start pos words[i].end) { wordIndex i; break; } } if (wordIndex ! this.data.currentWordIndex) { this.setData({ currentWordIndex: wordIndex }); } });这里还有一个常被忽略的性能细节onTimeUpdate每 250ms 触发一次但setData在小程序里是昂贵的操作。上面的代码先比较wordIndex是否变化再setData避免高频重复渲染同一份数据。对于 30 个字以内的句子这个量级的更新完全没问题如果以后要做整页长文本逐词高亮还需要升级成 WXS 响应式方案将高亮计算下放到渲染层彻底脱离setData的负担。验证这套时间轴是否对齐的办法很简单在页面上临时放一个调试文本直接显示currentTime、currentWordIndex和当前词的起止秒用真机播放后观察一旦某个句子“音画同步”但下一句偏移 200ms 以上问题一定出在音频文件剪裁上而不是代码。把start/end从句子级扩展到词级、再从词级扩展到拼音级这套时间轴数据模型就足以支撑点读、跟读、口语评测三种功能同时存在。本文还有配套的精品资源点击获取
