简介这是一份基于 Vue.js 与 JavaScript 构建音乐播放网站的前端项目源码面向具备一定前端基础、希望练习组件化开发与音频交互的开发者可用于课程设计、个人作品集或二次开发。项目围绕播放器、歌曲列表、搜索过滤、播放模式切换等模块展开涉及 Vue 数据绑定、组件封装、HTML5 Audio API 事件监听、axios 请求与 JSON 数据渲染以及 CSS3 过渡动画和 Flexbox 响应式布局等知识点。压缩包为 zip 格式整体约 84.53MB文件类型明细上游暂未提供但可预期包含 Vue 单文件组件、JavaScript 脚本、CSS 样式表及静态资源等便于按模块查阅与运行调试。目前已有 2046 人学习下载适合想通过完整案例理解音乐播放类应用实现思路、积累前端项目经验的读者参考借鉴。1. 从零搭一个 vue / js 音乐播放网站为什么很多人卡在“能播”和“好用”之间很多人第一次做 vue / js 音乐播放网站卡点不在“能不能出声”而在“能不能像正经播放器一样用”。我见过太多 Demo点一下歌能响切歌就白屏进度条拖不动刷新页面播放状态全丢。问题不在 Vue 本身而在于音频状态管理和浏览器音频策略这两块没打通。这个方向适合两类人一是想拿一个完整前端项目练手的 Vue 开发者二是需要给自家产品嵌一个轻量播放器的前端工程师。它不需要后端就能跑通核心链路但要做到“不翻车”你得把 Audio 对象、播放列表、进度同步、本地持久化这四件事串成一条线。下面我按实际落地顺序拆从最小可播版本一路做到能上线的播放器。2. 先定架构再写代码Audio 对象和 Vue 响应式怎么分工2.1 为什么不用 audio 标签直接绑 src最常见的写法是audio :srccurrentUrl controls简单但很快会遇到三个问题。第一切歌时 src 变化浏览器会重新加载整个音频进度、音量、播放速率全部重置用户体验是“每切一首都要重新缓冲”。第二controls原生控件的样式几乎无法深度定制做不了自定义进度条和歌词滚动。第三原生控件的事件和 Vue 响应式是两套体系你想在播放列表里高亮当前歌曲还得额外监听play、pause、ended再手动同步。我的做法是用一个new Audio()实例作为唯一播放源Vue 只负责“描述状态”Audio 实例负责“执行播放”。两者通过一个 composable 连接。这样切歌时只改audio.src不销毁实例音量、播放速率这些设置能保留。// composables/useAudioPlayer.js import { ref, shallowRef, onUnmounted } from vue export function useAudioPlayer() { // shallowRefAudio 实例不需要深度响应式避免性能损耗 const audio shallowRef(new Audio()) const isPlaying ref(false) const currentTime ref(0) const duration ref(0) const volume ref(0.8) // 绑定事件把 Audio 的原生状态同步回 Vue function bindEvents() { const el audio.value el.addEventListener(timeupdate, () { currentTime.value el.currentTime }) el.addEventListener(loadedmetadata, () { duration.value el.duration || 0 }) el.addEventListener(play, () { isPlaying.value true }) el.addEventListener(pause, () { isPlaying.value false }) el.addEventListener(ended, () { isPlaying.value false }) } function load(src) { audio.value.src src audio.value.load() // 显式触发加载保证 loadedmetadata 能拿到 duration } async function play() { try { await audio.value.play() } catch (err) { // 浏览器自动播放策略会在这里抛错后面章节专门讲 console.warn(播放被拦截:, err.name) } } function pause() { audio.value.pause() } function seek(time) { audio.value.currentTime time } bindEvents() onUnmounted(() { audio.value.pause() audio.value.src }) return { audio, isPlaying, currentTime, duration, volume, load, play, pause, seek } }逻辑说明shallowRef是关键Audio 实例内部属性极多用ref会把它整个代理一遍切歌时性能明显下降。事件绑定放在 composable 内部组件卸载时统一清理避免内存泄漏。load()里显式调用audio.load()是因为部分浏览器在只改src时不会立即触发元数据加载导致duration一直是 0。参数说明volume默认 0.8 是经验值1.0 在某些设备上会削波失真。seek直接赋值currentTime注意要在loadedmetadata之后调用否则会被浏览器忽略。2.2 播放列表状态该放 Pinia 还是组件内如果只有单个播放器组件ref数组就够了。但音乐播放网站通常有“列表页点歌 → 播放器页展示 → 迷你条常驻”三个位置共享状态这时候必须抽到 Pinia。我一般把“数据”和“播放控制”分开Pinia 存playlist、currentIndex、playModecomposable 只管 Audio 实例。这样播放器组件只订阅currentIndex变化变化时调用load()职责清晰。// stores/player.js import { defineStore } from pinia export const usePlayerStore defineStore(player, { state: () ({ playlist: [], // [{ id, title, artist, url, cover }] currentIndex: -1, playMode: order // order | loop | single | shuffle }), getters: { currentSong: (state) state.currentIndex 0 ? state.playlist[state.currentIndex] : null }, actions: { setPlaylist(list, index 0) { this.playlist list this.currentIndex index }, next() { if (!this.playlist.length) return if (this.playMode shuffle) { this.currentIndex Math.floor(Math.random() * this.playlist.length) } else { this.currentIndex (this.currentIndex 1) % this.playlist.length } }, prev() { if (!this.playlist.length) return this.currentIndex (this.currentIndex - 1 this.playlist.length) % this.playlist.length } } })逻辑说明next里对 shuffle 和顺序播放做了分支顺序播放用取模实现循环避免越界判断。currentSong用 getter 而不是在组件里算保证多个组件拿到的是同一份派生状态。参数说明playMode用字符串枚举而不是数字调试时一眼能看懂。setPlaylist第二个参数默认 0从列表页点第 N 首时传 N。3. 把播放链路跑通加载、播放、切歌、进度同步3.1 最小可播版本的完整调用顺序很多人写完 composable 和 store 后不知道怎么接起来。正确顺序是组件挂载时监听currentSong变化 → 变化时load(url)→ 用户点播放按钮时play()。注意不要在load后自动play因为浏览器会拦截非用户手势触发的播放。// components/Player.vue script setup import { watch } from vue import { storeToRefs } from pinia import { usePlayerStore } from /stores/player import { useAudioPlayer } from /composables/useAudioPlayer const store usePlayerStore() const { currentSong, isPlaying: storePlaying } storeToRefs(store) const { isPlaying, currentTime, duration, load, play, pause, seek } useAudioPlayer() // 监听当前歌曲变化只加载不播放 watch(currentSong, (song) { if (song?.url) load(song.url) }) function togglePlay() { if (isPlaying.value) pause() else play() } function formatTime(sec) { if (!sec || isNaN(sec)) return 00:00 const m Math.floor(sec / 60).toString().padStart(2, 0) const s Math.floor(sec % 60).toString().padStart(2, 0) return ${m}:${s} } /script template div classplayer button clicktogglePlay{{ isPlaying ? 暂停 : 播放 }}/button span{{ formatTime(currentTime) }} / {{ formatTime(duration) }}/span input typerange min0 :maxduration || 0 :valuecurrentTime inputseek($event.target.value) / /div /template逻辑说明watch只做load把“播放”留给用户点击这是绕开自动播放限制最稳的方式。进度条用input事件而不是change拖动时实时 seek松手即生效。formatTime对NaN做了兜底因为duration在元数据加载前是NaN。参数说明range的max绑duration || 0避免NaN导致滑块异常。seek传的是字符串Audio 会自动转数字但如果你要做严格类型检查可以Number()一下。3.2 切歌时进度条和播放状态怎么不串切歌最常见的 bug 是上一首的timeupdate还在触发新歌进度条先跳到旧值再归零。根因是load()之后currentTime没有立即重置而timeupdate是异步的。解决方式是在load里手动把currentTime置 0并且用一个loading标志位屏蔽旧事件。function load(src) { const el audio.value el.pause() currentTime.value 0 // 立即重置不等 timeupdate duration.value 0 el.src src el.load() }逻辑说明先pause再改src避免旧音频继续播放。手动置 0 是“后悔药”因为timeupdate触发频率约 4 次/秒不手动重置会有肉眼可见的跳变。参数说明如果要做淡入淡出可以在pause前用setInterval把volume降到 0再切歌切完升回来。这个后面进阶章节讲。4. 避坑与排查音乐播放网站最容易翻车的 5 个点4.1 点了播放没反应控制台报 NotAllowedError现象用户点击播放按钮代码执行了audio.play()但控制台抛NotAllowedError: play() failed because the user didnt interact with the document first。原因浏览器自动播放策略要求play()必须在用户手势click、touch的同步调用栈里触发。如果你在watch回调、setTimeout、await之后调用play()手势上下文已经丢失。解决把play()直接绑在按钮的click上不要在watch里自动播。如果业务必须自动播下一首用ended事件里调用play()在部分浏览器可行但更稳的是引导用户点一次“播放全部”之后同一会话内浏览器会放宽限制。4.2 duration 一直是 NaN 或 Infinity现象进度条max是 0总时长显示NaN:NaN。原因音频元数据还没加载完就读取了duration或者音频是流式返回服务端没给Content-Length浏览器算不出总时长。解决只在loadedmetadata事件里读duration并且加isFinite判断。如果是流式音频考虑用durationchange事件多次读取或者干脆不显示总时长只显示已播放时间。el.addEventListener(loadedmetadata, () { if (isFinite(el.duration)) duration.value el.duration })4.3 移动端切到后台再回来进度条卡死现象手机上锁屏或切到其他 App回来之后进度条不动了点播放也没反应。原因移动端浏览器在页面进入后台时会暂停音频部分机型还会销毁 Audio 上下文。timeupdate不再触发Vue 里的currentTime停在旧值。解决监听visibilitychange回到前台时用audio.currentTime强制同步一次。如果audio.paused为 true 但isPlaying为 true说明被系统暂停了把isPlaying置 false让用户手动恢复。document.addEventListener(visibilitychange, () { if (!document.hidden) { currentTime.value audio.value.currentTime if (audio.value.paused isPlaying.value) { isPlaying.value false } } })4.4 播放列表几百首时页面卡顿现象歌单一多滚动卡切歌慢。原因每首歌的封面图全部加载且列表项用了深度响应式对象。解决封面用loadinglazy列表数据用markRaw或shallowRef包一层避免 Vue 对每首歌的每个字段做代理。虚拟滚动是终极方案但一般 200 首以内用懒加载就够。4.5 刷新页面播放状态全丢现象用户听到一半刷新回到初始状态。原因Vue 的响应式状态存在内存里刷新即销毁。解决把currentSong.id、currentTime、playlist存localStorage初始化时读回来。注意只存 id 和进度不存整个 Audio 实例。恢复时load后seek到上次进度但不要自动play等用户点。// 保存 watch([currentSong, currentTime], () { if (currentSong.value) { localStorage.setItem(lastPlay, JSON.stringify({ id: currentSong.value.id, time: currentTime.value })) } }, { deep: false })5. 进阶技巧让播放器从“能用”到“顺手”的三个细节5.1 用 Web Audio API 做音量淡入淡出原生audio.volume直接改会“啪”一声因为音量是瞬间跳变的。要做平滑过渡得用AudioContext包一层 GainNode。注意这会把音频路由到 Web Audio 图里移动端需要用户手势后才能resume()。let audioCtx, gainNode, sourceNode function initWebAudio(audioEl) { audioCtx new AudioContext() sourceNode audioCtx.createMediaElementSource(audioEl) gainNode audioCtx.createGain() sourceNode.connect(gainNode) gainNode.connect(audioCtx.destination) } function fadeTo(target, duration 300) { const now audioCtx.currentTime gainNode.gain.cancelScheduledValues(now) gainNode.gain.setValueAtTime(gainNode.gain.value, now) gainNode.gain.linearRampToValueAtTime(target, now duration / 1000) }逻辑说明cancelScheduledValues清掉未执行的渐变避免连续切歌时音量叠加。linearRampToValueAtTime做线性过渡300ms 是听感上比较自然的时长。参数说明target传 0 做淡出传 1 做淡入。如果用户手动拖了音量条要同步更新gainNode.gain.value否则下次淡入会跳回旧值。5.2 歌词滚动用 requestAnimationFrame 而不是 timeupdatetimeupdate每 250ms 才触发一次歌词高亮会一顿一顿。要丝滑用requestAnimationFrame每帧读audio.currentTime再二分查找当前歌词行。function startLyricLoop(lyrics) { let rafId function tick() { const t audio.value.currentTime // lyrics 是按时间排序的 [{ time, text }] let lo 0, hi lyrics.length - 1, idx -1 while (lo hi) { const mid (lo hi) 1 if (lyrics[mid].time t) { idx mid; lo mid 1 } else hi mid - 1 } activeLine.value idx rafId requestAnimationFrame(tick) } tick() return () cancelAnimationFrame(rafId) }逻辑说明二分查找把每帧的复杂度从 O(n) 降到 O(log n)歌词几百行也不掉帧。activeLine变化时 Vue 只更新那一行的高亮 class。参数说明lyrics必须按time升序排好解析 LRC 时就要排。rafId在组件卸载时取消否则会一直跑。5.3 播放模式切换的边界处理顺序、循环、单曲、随机四种模式最容易错的是“单曲循环”和“随机”在ended事件里的分支。单曲循环要currentTime 0; play()而不是next()。随机模式要避免连续两次随机到同一首否则用户以为卡了。audio.value.addEventListener(ended, () { const mode store.playMode if (mode single) { audio.value.currentTime 0 audio.value.play() } else if (mode shuffle) { let next store.currentIndex while (next store.currentIndex store.playlist.length 1) { next Math.floor(Math.random() * store.playlist.length) } store.currentIndex next } else { store.next() } })逻辑说明单曲循环不走next直接重置进度。随机模式用 while 重摇列表长度大于 1 时才重摇避免死循环。参数说明store.playlist.length 1这个判断不能省只有一首歌时随机等于单曲重摇会卡死。我自己的习惯是每做完一个播放器先拿手机连蓝牙耳机测一遍切歌和锁屏再拿 Chrome 的 Network 面板把音频请求限速到 3G 测一遍缓冲表现。这两个场景能暴露八成以上的坑。希望帮到你。本文还有配套的精品资源点击获取