简介一款面向微信小程序初学者的在线音乐示例工程适配1028版本压缩包内置完整源代码与运行截图可直接导入开发者工具体验音乐列表播放与页面交互效果。资源一共41个文件压缩包约72KB主要类型包含10张png预览图、8个wxml页面模板、8个js页面逻辑、7个wxss样式、5个json配置以及Markdown说明和TypeScript类型文件体量轻但覆盖小程序基础工程所需模块。目录按pages、utils、typings组织app.json定义全局配置app.js处理入口逻辑app.wxss统一全局样式README提供使用提示能帮助读者快速理解在线音乐小程序从页面渲染、样式布局到数据交互的完整流程。已有467人学习使用适合刚接触微信小程序、希望以轻量案例掌握项目结构与基础开发的初学者。1. 在线音乐微信小程序 demo别纠结 1028 是哪个版本先让播放链路跑通在下载到的源码包里“在线音乐 1028 源代码 截图”这个组合很常见多半是课程作业、外包交接或毕业设计项目的快照。先把 1028 理解成打包人自己的标识更稳妥它不一定是官方基础库版本号真正决定 demo 能不能复现的是三件事音频接口用的是哪一代 API、音频直链是否满足合法域名要求、播放器在页面销毁后有没有被正确接管。这篇按原生小程序的路径用 InnerAudioContext 做主播放器把列表、播放、进度、后台播放和真机验证串起来目录结构直接给到可导入微信开发者工具的状态适合正在补作业也想顺手把边界摸清楚的人。2. 在线音乐播放器的核心选型InnerAudioContext、BackgroundAudioManager 与老接口的边界2.1 先看在线音乐 demo 需要哪几块能力在线音乐小程序做“最小可运行版”界面可以简陋但音频链路不能简化。我一般把能力拆成五块歌单列表、播放页、进度与控制、切歌、后台播放。列表决定需要几个页面后面四项决定音频 API 的选型。很多源码包里的播放页只做到“点按钮响一声”demo 能过但这是把音频上下文放在页面局部变量里的结果页面一切走就失效。这里要摆正一个概念小程序没有网页那种全局audio标签任何音频接口最终都要绑定一个音频上下文并自己管理它的生命周期。所以第一步不该急着写 WXML而是先想清楚用哪个 API 持有这个上下文。API后台播放事件能力当前状态在 1028 源码包里的典型位置wx.playBackgroundAudio支持弱已停止维护早期教程和老代码wx.createInnerAudioContext默认不支持完整推荐页面内播放demo 主力wx.getBackgroundAudioManager支持完整推荐需要锁屏控制或后台播放时2.2 为什么 1028 源码包里的 wx.playBackgroundAudio 不值得继续抄wx.playBackgroundAudio 是早期基础库提供的后台播放接口调用简单但状态同步很别扭。它没有一个可靠的“当前播放歌曲 id”回读机制播放列表由开发者自行维护切歌、暂停、结束这些状态容易对不上。真机上它经常因为 iOS 锁屏控制中心和音频中断事件出现行为漂移调试成本远高于写一遍新接口。所以现在收到这类源码正确做法不是修它而是整个替换。wx.createInnerAudioContext 是目前页面内播放最稳的接口事件覆盖 onPlay、onPause、onStop、onEnded、onTimeUpdate、onError状态靠 currentTime、duration、paused 这些字段直接拿。它默认不支持后台播放这是设计如此不是 bug。如果业务必须切后台继续响就换 wx.getBackgroundAudioManager。一个常见误区是写过 InnerAudioContext 后发现切后台就断又去 hack 定时器得不偿失。2.3 音频上下文放在 Page 上是最典型的复用问题初版 demo 最常见的写法是在播放页 onLoad 里this.audioCtx wx.createInnerAudioContext()onUnload 里 destroy。这样列表页和播放页各自持有一个播放器切页就重置无法做到“从列表进详情继续放同一首”。我一般建议把音频上下文提升到 App.globalData 或独立单例模块里页面只负责绑事件和更新 UI。这样列表页、播放页、未来的歌词页拿到的都是同一个上下文状态不会漂移。下一章按这种思路给目录结构和源码。3. 用独立歌曲配置搭出最小可运行 demo从源代码到播放页3.1 建立项目目录并用微信开发者工具导入按原生小程序目录搭不用 HBuilderX 和 uni-app因为没有框架转换层方便直接看到 1028 这类源码包里最常见的组织方式。目录如下wechat-music-demo/ ├── app.js ├── app.json ├── app.wxss ├── data/ │ └── songs.js └── pages/ ├── index/ │ ├── index.js │ ├── index.wxml │ ├── index.wxss │ └── index.json └── player/ ├── player.js ├── player.wxml ├── player.wxss └── player.jsonsongs.js 是纯数据模块好处是换歌单、换音频直链时不用翻页面代码。导入时在微信开发者工具选择“导入项目”AppID 用测试号即可。如果代码是从压缩包解出来的先检查 app.json 里 pages 路径是否和实际目录对得上这一步比改播放器代码更容易被忽略。3.2 app.json 与歌曲数据拆分app.json 注册两个页面并调整导航栏颜色让播放页看起来更像音乐 App。这里不声明 requiredBackgroundModes因为当前方案用 InnerAudioContext留到第 4 章需要后台播放时再补。{ pages: [ pages/index/index, pages/player/player ], window: { navigationBarTitleText: 在线音乐, navigationBarBackgroundColor: #1e1e1e, navigationBarTextStyle: white } }navigationBarTextStyle 在深色导航栏上必须配 white否则白底配黑字状态栏完全看不清。接下来 songs.jsconst songs [ { id: 1, title: 网易云示例曲, artist: Demo Artist, cover: /assets/cover-demo.jpg, url: https://example.com/music/demo-1.mp3 }, { id: 2, title: 在线音乐试听, artist: CDN Test, cover: /assets/cover-test.jpg, url: https://example.com/music/demo-2.mp3 } ]; module.exports { songs };3.3 列表页到播放页的参数传递首页只负责展示列表并跳转播放逻辑不写在首页。index.js 用>const { songs } require(../../data/songs.js); Page({ data: { songs }, play(e) { const id e.currentTarget.dataset.id; wx.navigateTo({ url: /pages/player/player?id${id} }); } });对应 index.wxml 用 wx:for 渲染注意 wx:key 用 id避免列表重排时出现渲染异常view classsong-list view wx:for{{songs}} wx:keyid classsong-item >const app getApp(); const { songs } require(../../data/songs.js); function getAudio() { if (!app.globalData.audioContext) { app.globalData.audioContext wx.createInnerAudioContext(); } return app.globalData.audioContext; } Page({ data: { song: null, playing: false, currentTime: 0, duration: 0, percent: 0 }, onLoad(query) { const id Number(query.id); const song songs.find(item item.id id); this.audio getAudio(); this.setData({ song }); if (this.audio.src ! song.url) { this.audio.stop(); this.audio.src song.url; } this.audio.play(); }, onUnload() { this.audio.pause(); } });onLoad 里先比对 src 再赋值是为了避免重复点击同一首歌时重新设置 src 导致音频重载。stop 会结束本次播放并触发 onStop若旧曲子和新曲子是同一首就不做任何重置。onUnload 只 pause 不 destroy是保证下次进来还能继续播同一首的关键。这里的取舍是如果你希望每次离开播放页都彻底停止就在 onUnload 里 stop 而不是 pause。4. 播放器参数与真机排错进度条、音频直链和顶部导航栏4.1 InnerAudioContext 的常用参数与默认行为即使不写任何事件监听直接 src 加 play 也能出声但真机表现会和模拟器差很远。下面这张表是我在交付 demo 前必查的参数参数默认值作用建议src空音频资源地址必须是 HTTPS 直链autoplayfalse设置 src 后是否自动播放demo 里常用 trueloopfalse是否循环播放音乐类场景通常关掉volume1音量 0 到 1需要单曲音量时调playbackRate1播放速率变速播放时使用obeyMuteSwitchtrueiOS 上是否跟随静音键音乐 App 建议设 falseobeyMuteSwitch 这一个参数最容易被漏。iPhone 侧边静音键打开时默认 true 会让 InnerAudioContext 静音用户以为程序坏了。做音乐播放器一般把 obeyMuteSwitch 设为 false播放器声音不走静音键只受音量键控制。4.2 进度条 slider 与 onTimeUpdate 联动进度条用小程序原生 sliderpercent 字段绑定拖拽位置。监听 onTimeUpdate 更新播放进度代码结构如下slider value{{percent}} bindchangingonSeeking bindchangeonSeeked activeColor#ff4d4f block-size14 /bindchanging 是拖动过程bindchange 是松手确认。如果每次 changing 都调用 seek音频会频繁跳变。正确做法是拖动过程只更新本地 percent松手时再 seekonSeeking(e) { this.setData({ percent: e.detail.value }); }, onSeeked(e) { const duration this.audio.duration || 1; const target (e.detail.value / 100) * duration; this.audio.seek(target); }, onTimeUpdate() { const duration this.audio.duration || 0; const percent duration 0 ? Math.floor((this.audio.currentTime / duration) * 100) : 0; this.setData({ currentTime: this.audio.currentTime, duration, percent }); }注意this.audio.duration在音频刚加载时可能是 0 或 NaN必须做兜底。另外 seek 是异步操作在真机上连续快速拖动会触发多次 seek旧 seek 可能覆盖新位置所以产品级的做法要加节流。对 demo 来说松手才 seek 已经够用。4.3 音频直链http、域名、防盗链在线音乐的音频源是外链问题一般出在三处。第一处是协议微信小程序要求请求地址为 HTTPS开发者工具在勾选“不校验合法域名”时允许 http真机直接失败。第二处是域名要在小程序管理后台把音频所在域名的 request 合法域名加进白名单且不能带端口。第三处是防盗链部分 CDN 会校验 Referer 或自定义 Header小程序音频请求没法像 Web 那样自由改 Headers遇到 403 只能换源。真机排错时优先看 console 里的 errMsg。常见的网络错误会直接出现在 onError 里把错误上报到页面顶部或 console.tablethis.audio.onError(err { console.table({ code: err.errCode, message: err.errMsg }); });调试阶段可以在开发者工具右上角勾选“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”但这只是开发便利正式演示前必须换回合法域名。若是接的第三方音乐接口返回 302 跳转确认最终落点仍是 HTTPS否则播放器不会跟随。4.4 顶部导航栏高度对播放页布局的影响播放页如果要做自定义导航栏就必须知道顶部导航栏高度。微信从某版本开始推荐用 wx.getMenuButtonBoundingClientRect 获取胶囊按钮位置再用系统状态栏高度算出导航栏真实高度const systemInfo wx.getSystemInfoSync(); const menuRect wx.getMenuButtonBoundingClientRect(); const navHeight (menuRect.top - systemInfo.statusBarHeight) * 2 menuRect.height;menuRect.top 和 statusBarHeight 配合能得到状态栏到胶囊的间距乘 2 是因为胶囊上下间距对称。这个高度在 iPhone 上大约是 44Android 上浮动更大写死任何数值都会在某台设备上错位。如果你的 demo 播放页顶部是封面封面下压导航栏让人不适就用这个公式动态设置 paddingTop。4.5 需要后台播放时换成 BackgroundAudioManagerInnerAudioContext 默认不支持后台播放如果交付要求“锁屏后继续响”就要把播放器核心换成 wx.getBackgroundAudioManager。这是一个全局单例不需要自己创建const bgAudio wx.getBackgroundAudioManager(); bgAudio.title song.title; bgAudio.singer song.artist; bgAudio.epname 在线音乐 demo; bgAudio.src song.url; bgAudio.play();顺序有讲究先设置标题和歌手最后赋值 src。因为 src 一旦赋值就会触发加载播放如果 title 还没写锁屏控制中心里显示的会是空标题。另外 app.json 需要声明requiredBackgroundModes: [audio]否则切后台会被系统挂起。这个字段在小程序审核时比较敏感个人 demo 自用可以上架前务必确认业务确实需要后台播放不然基本过不了审。5. 从截图到在线播放验收单例组件与真机调试5.1 把播放逻辑抽成单例页面只做 UI 绑定交付源码时截图往往只展示界面但代码复用度才是拉开作业差距的地方。建议把 createInnerAudioContext 的创建和全局事件监听收进 utils/player.jslet audio null; function getPlayer() { if (!audio) { audio wx.createInnerAudioContext(); audio.onError(err { console.error(audio error:, err); }); } return audio; } module.exports { getPlayer };模块级变量在微信小程序 require 机制下是共享的多个文件 require 同一个 player.js拿到的 audio 是同一个实例。这样首页可以调用getPlayer().play()播放页只负责展示当前歌曲信息。对 1028 这类源码包把散落在页面里的音频代码收拢比加注释更有维护价值。5.2 真机调试与“当前不会命中断点”在微信开发者工具里打断点经常看到“当前不会命中断点”这通常不是源码丢失而是断点落在 ES6 转 ES5 后的代码上sourceMap 没有对应回去。我一般不会在播放器事件回调里打断点直接改用 console.log 打印音频状态因为 onTimeUpdate 每秒触发几十次断点会让人误判成卡死。真机调试时优先看 Network 面板里音频请求的响应状态代码层面则通过 wx.getNetworkType 判断是 WiFi 还是 4G 下的播放问题。如果一定要抓包确认 Range 请求是否生效优先用真机调试自带的网络面板比外部抓包工具少踩证书坑。5.3 截图与验收清单截图是交付的一部分但别只截播放页。建议按以下顺序留档列表页三首歌以上能看到封面和 1028 标识播放页显示可拖动进度条和循环状态控制台无 404 和音频错误。最后重新编译观察 Network音频请求应只发一次切歌后旧连接被 close这个状态出现在线播放链路才算真正通。本文还有配套的精品资源点击获取