企业官网建设流程全解析

简介：这是一份基于 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 :src="currentUrl" 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() { // shallowRef：Audio 实例不需要深度响应式，避免性能损耗 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、playMode，composable 只管 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 class="player"> <button @click="togglePlay">{{ isPlaying ? '暂停' : '播放' }}</button> <span>{{ formatTime(currentTime) }} / {{ formatTime(duration) }}</span> <input type="range" min="0" :max="duration || 0" :value="currentTime" @input="seek($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 didn't 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 播放列表几百首时页面卡顿

现象：歌单一多，滚动卡，切歌慢。

原因：每首歌的封面图全部加载，且列表项用了深度响应式对象。

解决：封面用loading="lazy"，列表数据用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 而不是 timeupdate

timeupdate每 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 测一遍缓冲表现。这两个场景能暴露八成以上的坑。希望帮到你。

本文还有配套的精品资源，点击获取