简介这份资源是一套可直接导入微信开发者工具运行调试的微信小程序音乐播放器工程面向想要入门小程序开发或实现音乐类应用的开发者。项目现已上线微信小程序可搜索“ChickenMusic音乐播放器”体验功能覆盖首页搜索、轮播图、热门榜单与歌单正在播放页的进度展示、歌词同步滚动、单曲循环/列表循环/随机播放以及歌手详情、最近播放、收藏列表页面与逻辑模块划分清晰。压缩包共102个文件以js逻辑、json配置、wxml页面结构、wxss样式为主另含png/gif图片素材和md说明文档总大小仅728KB轻量且易于阅读。目前已有3951人浏览学习适合作为小程序教学案例或二次开发底座。通过阅读代码可掌握页面数据绑定、request请求封装、AudioContext播放器控制、歌词解析与同步等核心写法快速提取可复用的组件与交互思路。1. 这个微信小程序音乐播放器源码包值得拆开看的不只是播放页wxmusic 这个微信小程序音乐播放器源码包打开后最先看到的是 loading.gif、playing.gif 两张演示图真正值得读的是 lyric.js、player.js、api.js 这一组模块。它实现了一个上线过的小程序包含首页搜索、轮播图、榜单、热门歌单、正在播放、歌词同步滚动、播放模式切换、歌手列表、最近播放和收藏。对想在小程序里做音频播放的开发者来说这个包的价值不只是功能能跑通而是能看到播放器状态、歌词解析和网络请求这三层怎么拆开以及各自在页面里承担什么角色。下面的内容按我实际拆包和复跑的顺序把每个文件的关键实现和容易踩的坑过一遍。2. 模块拆分与数据流先看懂 js 文件之间的依赖关系2.1 文件清单里的职责边界拿到源码先看文件列表几乎每个 js 对应一个清晰的职责。我拆解后整理了下面这张表文件职责关键依赖index.js首页数据加载、搜索入口、轮播图和榜单跳转api.jsplayer.js播放器状态机处理播放/暂停/切歌和三种模式api.jslyric.js歌词解析、时间轴计算、当前行定位无api.js封装 wx.request统一返回 Promise无search.js搜索页防抖、关键字请求、结果展示api.jswatch.js监听音频进度并回调驱动进度条和歌词无music-list.js通用歌单/榜单/歌手歌曲列表api.jssinger.js歌手列表和歌手详情跳转api.js这个拆法很实用lyric.js 不依赖任何小程序 API可以脱离 UI 单测api.js 单独封装后页面里不需要重复处理状态码player.js 和 watch.js 之间通过回调而不是直接 setData避免把播放状态和页面状态强耦合。我一般拿到别人的小程序源码会先按这张表还原数据流再动手改代码否则很容易被页面里一堆 bindtap 淹没。2.2 数据流从首页到播放页的参数传递首页往往一次拿回多个榜单、歌单和搜索列表点击其中一首歌时常见做法不是把整首歌对象塞到 URL 里而是只传 songid 和 index把完整列表放到全局数据中。这样播放页可以向前向后切歌不用重新请求。// index.js 中点击歌曲时的跳转 handlePlay(e) { const { songid, index } e.currentTarget.dataset; const list this.data.currentList; // 当前榜单或搜索结果的歌曲列表 getApp().globalData.playlist list; wx.navigateTo({ url: /pages/player/player?songid${songid}index${index} }); }这里有两个关键点songid 用于播放页单独取详情或封面index 决定初始播放位置globalData.playlist 保证切歌时拿到的还是用户进入播放页时的那份列表。如果直接把列表拼接在 url 里遇到超长歌名或者几十首歌曲的数组很容易超出小程序页面路径长度限制而且每次页面加载都要重新解析字符串点击响应会变慢。2.3 api.js 的 Promise 封装微信小程序的 wx.request 默认是回调写法页面一旦多了就会出现嵌套回调。源码里的 api.js 通常会把请求包成 Promise 并统一处理业务状态码// api.js 的常见封装写法 const BASE_URL https://your-api-host.com/api/v1; function request(path, data {}) { return new Promise((resolve, reject) { wx.request({ url: ${BASE_URL}${path}, data, success: (res) { if (res.statusCode 200 res.data.code 0) { resolve(res.data.data); } else { reject(res.data); } }, fail: (err) reject(err) }); }); } module.exports { search: (keyword) request(/search, { keyword }), hotList: () request(/toplist), songDetail: (id) request(/song/detail, { id }) };这段代码里的 code 0 是业务层约定的成功状态如果你的后端返回的 code 不是这个记得统一改这里不用在每个页面里调整逻辑。fail 分支也做了透传这样页面里用 async/await 包一层 try/catch 就能捕获所有异常。BASE_URL 要注意不能写死内网 IP真机运行时小程序无法访问局域网 IP除非打开调试模式这一点在最后一章会展开。2.4 导航栏高度和加载态容易被忽略的适配很多二次开发的人会把精力放在音乐播放上忽略顶部导航栏的高度适配。这个项目里如果用了自定义导航栏通常需要动态获取状态栏高度和胶囊按钮位置不同机型差异很大。const { statusBarHeight } wx.getSystemInfoSync(); const { top, height } wx.getMenuButtonBoundingClientRect(); const navBarHeight (top - statusBarHeight) * 2 height;statusBarHeight 是状态栏高度top 是胶囊按钮上边缘到屏幕顶部的距离两者相减得到胶囊按钮离状态栏底部的间距再乘 2 加上按钮自身高度能算出比较接近实际的自定义导航栏高度。把这个值放到全局 data 里页面样式就能统一适配否则在 iPhone X 和普通安卓机上会出现标题下移或遮挡的问题。另外首页加载时最好用 loading.gif 这类占位资源承接而不是直接白屏给用户一个“数据正在回来”的预期。3. 播放核心 player.js 与 watch.js 的状态机设计3.1 初始化音频上下文播放器的底座是 wx.createInnerAudioContext这个 API 比 wx.getBackgroundAudioManager 轻量不需要在后台播放时也能用适合做页面内播放。player.js 里一般会先创建一个音频实例并设置 src 和开始播放// player.js 初始化音频实例 this.audioCtx wx.createInnerAudioContext(); this.audioCtx.src song.url; this.audioCtx.play();这里要注意 src 必须是以 https 开头的完整地址不能是相对路径或 base64在开发者工具里域名校验关闭后也可以用 http但真机预览时还是必须配置合法域名。audioCtx 创建后要把 onTimeUpdate、onEnded 的回调注册好事件回调中的 this 会丢失所以通常用箭头函数或提前 bind否则访问不到页面上的 setData。3.2 三种播放模式的切换逻辑播放模式是这个项目功能表里明确列出的一项包括列表循环、单曲循环、随机播放。可以用一个整型字段 mode 表示0 列表循环1 单曲循环2 随机播放。切换模式只需要在设置里取模即可。mode含义下一首逻辑0列表循环(current 1) % length1单曲循环current2随机播放random 且避免与当前索引相同对应的核心函数如下function getNextIndex(mode, current, length) { if (length 0) return -1; if (mode 1) return current; if (mode 2) { let next Math.floor(Math.random() * length); if (next current length 1) { next (next 1) % length; } return next; } return (current 1) % length; }这个函数是纯计算不依赖任何小程序环境可以直接在 Node 里单测。params 中 length 是播放列表长度current 是当前索引。随机播放里避免重复的逻辑如果随机出来和当前索引一样就自动后移一位当列表只有一首歌时取 current 本身也是对的所以加 length 1 才做后移。audioCtx 的 ended 事件里拿到这个索引后需要更新时间、清空歌词、设置新 src 并重新 play。切歌时最容易犯的错是没有先 reset 播放页的 currentTime 和歌词行号导致新歌在旧歌词上闪一下。3.3 watch.js 的进度监听歌词滚动和进度条都需要一个稳定的时间基准。常见错误是用 setInterval 每 250ms 读一次 audioCtx.currentTime但小程序里 currentTime 是异步更新的setInterval 读到的一段时间内可能都是同一个值而且定时器在页面切后台后可能被冻结。更符合小程序习惯的是 watch.js 基于 onTimeUpdate 做回调// watch.js 播放进度观察 function watchProgress(audioCtx, cb) { audioCtx.onTimeUpdate(() { if (typeof cb function) { cb({ currentTime: audioCtx.currentTime || 0, duration: audioCtx.duration || 0 }); } }); }onTimeUpdate 的触发频率由系统控制通常在 200ms 到 500ms 之间歌词滚动完全够用。回调里只传 currentTime 和 duration页面拿到后再决定更新进度条还是歌词这样的好处是 watch.js 不需要知道页面的具体结构。注意 duration 在某些音频源加载完成之前是 0 或 NaN所以拿不到时长时不要立刻计算进度比例等 onCanplay 或 onLoadedMetaData 触发后再补一次进度刷新。3.4 页面卸载和切歌时的事件清理音频实例如果不销毁会持续占用播放器资源甚至导致再次进入播放页时声音重叠。player.js 里应有对应的清理逻辑onUnload() { if (this.audioCtx) { this.audioCtx.stop(); this.audioCtx.destroy(); this.audioCtx null; } }destroy 会释放资源并移除所有已注册的事件监听比手动 off 更省事。但如果你的代码里注册了 onTimeUpdate 后又用 onError切换页面时不需要逐条 off直接 destroy 即可。实际调试中碰到过一种情况从播放页返回首页后歌曲还在继续响原因就是只调了 stop 没调 destroy。另外切歌时要手动把歌词滚动偏移和播放进度条归零避免上首歌的进度短暂覆盖新歌。4. 歌词同步滚动lyric.js 的解析与定位4.1 时间标签解析歌词同步的核心是把 LRC 时间标签转换成可比较的数值。LRC 格式通常是[mm:ss.xx]或[mm:ss.xxx]后面跟着歌词文本。lyric.js 里解析函数一般这样写// lyric.js 解析 LRC 歌词 function parseLyric(lyric) { const lines lyric.split(\n); const tracks []; for (const line of lines) { const match line.match(/\[(\d{2}):(\d{2})\.(\d{2,3})\](.*)/); if (!match) continue; const min parseInt(match[1], 10); const sec parseInt(match[2], 10); const msRaw match[3]; const ms msRaw.length 2 ? parseInt(msRaw, 10) * 10 : parseInt(msRaw, 10); tracks.push({ time: min * 60 * 1000 sec * 1000 ms, text: match[4].trim() }); } return tracks.sort((a, b) a.time - b.time); }这里的 match[3] 可能是两位数也可能是三位数两位时代表百分之一秒所以要乘 10 转成毫秒三位本身已经是毫秒。time 统一用毫秒是为了后面和当前音频时间的 currentTime * 1000 直接比较避免小数精度问题。排序那一步不能省有些 LRC 文件时间顺序是乱的排序后定位才不会跳来跳去。4.2 根据当前时间定位高亮行拿到 tracks 数组后每次 onTimeUpdate 都要找出“当前时间对应第几行”。常见做法是正向遍历function getCurrentLine(tracks, currentMs) { let index 0; for (let i 0; i tracks.length; i) { if (currentMs tracks[i].time) { index i; } else { break; } } return index; }这个循环里 tracks 已经按时间排序第一个大于当前时间的行就是下一句而 index 保留当前句。因为歌词一般不会超过几百行循环性能没问题。如果歌词非常大也可以做二分法但对小程序来说没必要。定位到当前行后需要把 scroll-view 滚到合适的位置让这一行居中。假设每行高度是 40 像素歌词展示区高度 240 像素const lineHeight 40; const viewHeight 240; const offset currentLine * lineHeight - (viewHeight - lineHeight) / 2; this.setData({ currentLine: currentLine, scrollOffset: offset 0 ? 0 : offset });这里 scrollOffset 是 scroll-view 的 scroll-top 值。为什么要减掉半个可视区高度因为用户视线集中在屏幕中央歌词行保持在中间比顶在顶部体验好得多。小于 0 时没有内容可滚要手动置 0否则 scroll-view 在安卓上可能出现回弹异常。4.3 歌词与播放器的联动细节项目中 lyric.js 一般只导出 parseLyric 和 getCurrentLine 这类纯函数页面负责把 audioCtx 的 currentTime 乘以 1000 后传入。播放暂停时不需要额外处理因为 currentTime 停止变化当前行不会跳。切歌时则要把 currentLine 和 scrollOffset 都 reset 成 0同时清掉正在展示的歌词文本否则新歌会先闪出上一首的末行。如果做了“点击歌词跳转播放时间”的功能需要在点击事件里把 currentTime 赋值给 audioCtx并同步更新 highline 当前行。// 点击歌词行跳转播放 onLyricTap(e) { const idx e.currentTarget.dataset.index; const targetTime tracks[idx].time / 1000; this.audioCtx.seek(targetTime); this.setData({ currentLine: idx, scrollOffset: idx * lineHeight }); }seek 后的 currentTime 不会立刻变成目标值需要在 onTimeUpdate 里再做一次 align否则歌词行和音频会把短暂错位。这里还要注意 seek 在 iOS 和安卓上精度表现不一样安卓部分机型需要先 pause 再 seek 再 play 才能生效但目前大部分版本已经修复。5. 搜索、榜单、歌手页面的数据对接与列表复用5.1 搜索框防抖search.js 负责搜索功能最核心的是输入防抖。微信小程序中没有原生的 debounce需要自己用 setTimeout 实现// search.js 的搜索防抖 let searchTimer null; function onSearchInput(e) { const keyword e.detail.value.trim(); clearTimeout(searchTimer); if (!keyword) { this.setData({ searchList: [], hasSearched: false }); return; } searchTimer setTimeout(() { this.fetchSearch(keyword); }, 300); }300ms 是一个平衡值如果小于 200ms连续输入会发太多请求如果大于 500ms用户等待感明显。注意在 fetchSearch 里也要带上 try/catch防止请求失败后搜索框一直转圈。搜索页还可以把最近热词放在页面上用户点热词直接触发防抖逻辑这里的 setData 只更新 searchList 和 hasSearched不要覆盖 input 的 value避免光标跳动。5.2 榜单和歌单的请求与跳转首页的轮播图、榜单、热门歌单三块数据通常来自三个接口但都走 api.js。榜单展示的往往是榜单概况点击后要进入 music-list 页面显示榜单内的歌曲。music-list.js 是一个通用列表页通过页面参数 type 区分是榜单还是歌手歌曲。页面参数接口pages/index/index无banner、toplist、hotPlaylistpages/music-list/music-listid typetoplist榜单歌曲pages/music-list/music-listid typesinger歌手歌曲pages/singer/singer无歌手列表这种设计的好处是不需要给每个榜单写一个页面加载更多、下拉刷新、播放跳转都复用同一个逻辑。我在改这类页面时会注意如果榜单返回的歌曲数组已经带了 songId就不需要再额外请求歌曲详情直接丢给 player如果只有歌名点击播放前要先拼接播放地址。5.3 歌手列表与详情singer.js 加载歌手列表后点击某个歌手跳转到 music-list。这里的关键是参数传递和榜单共用一个页面// singer.js 跳转到歌手歌曲列表 onSingerTap(e) { const { singerId, singerName } e.currentTarget.dataset; wx.navigateTo({ url: /pages/music-list/music-list?id${singerId}typesingertitle${encodeURIComponent(singerName)} }); }music-list.js 的 onLoad 里通过 options.type 决定请求哪个接口再根据 title 设置页面标题。这里的 title 要用 encodeURIComponent 编码不然歌手名里带中文和特殊符号会导致页面路径解析失败。实际项目中还会把歌手 ID 存进全局方便播放页展示歌手信息。5.4 最近播放和收藏的本地存储“我的”页面需要展示最近播放和收藏由于数据量不大完整项目里通常用 wx.setStorageSync 做本地存储。最近播放列表要注意去重和长度限制const RECENT_KEY recent_play; function addRecentPlay(song) { let list wx.getStorageSync(RECENT_KEY) || []; list list.filter(item item.songId ! song.songId); list.unshift(song); if (list.length 50) { list.length 50; } wx.setStorageSync(RECENT_KEY, list); }先过滤掉同一首再 unshift 到最前面保证最近播放顺序正确。限制 50 条是因为 Storage 有 10MB 上限歌曲字段少没关系但有些接口会把完整歌词或 MV 播放地址一起返回存进去就很不划算。收藏列表可以同样处理但取消收藏时还要同步更新 UI要避免一边写 Storage 一边 setData 大数组。6. 让这个播放器在真机上跑起来域名、缓存与排查技巧6.1 开发者工具里的三个关键配置首先没有自己的 AppID 就选测试号。测试号可以正常开发但不能真机预览部分能力。其次在“详情 - 本地设置”里勾选“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”这样开发者工具里能请求 http 接口。最后项目里的 appid 如果被换过project.config.json 里的 appid 也要同步改否则会报 appid 不匹配。# 在项目根目录查看当前 appid 配置 cat project.config.json | grep appid这个命令可以快速确认工具读到的 appid 和你在开发者工具里登录的是否一致。很多时候“打开项目空白页”不是代码问题而是 appid 无效导致微信没有正确编译。所以第一次打开源码包时别急着改代码先检查这个文件。6.2 外链资源失效的排查思路音乐播放类小程序最大的变数是歌曲外链。遇到播放不了先打开开发者工具的 Network 面板看请求歌曲 URL 的返回码。如果返回 403多半是防盗链后端代理加 Referer 头即可。如果返回 200 但播放没声音可能是音频格式不对iOS 不支持某些 mp3 编码转成标准 AAC 或 MP3 即可。歌词接口同理出现整页有歌名但没有歌词先请求歌词文本再检查 lyric.js 解析出来的 time 是否为 0如果是看看是不是被人为去掉了时间标签。6.3 保持歌词和播放器模块可复用最后给一个我实际改项目的建议把 lyric.js 里的 parseLyric、getCurrentLine 导出成纯方法页面里的 onTimeUpdate 只负责拿时间和计算偏移不要直接操作 DOM。这样以后接 new Audio 或者换播放库歌词部分不用动。播放器如果要做后台播放把 wx.createInnerAudioContext 换成 wx.getBackgroundAudioManager并额外设置 title、coverImgUrl、epname、singer才能在后台播放时控制系统通知栏。真机验证时建议先只跑榜单和播放页确认音频链路正常后再加搜索和歌手页每一步都能快速定位问题所在。本文还有配套的精品资源点击获取