网页游戏“电话留言系统”从零实现：音频播放器状态机与资源管理

做开发的同学应该都有过这种体会：产品经理丢过来一个需求，看起来特别简单，落到细节却全是坑。比如“在页游里加一个电话留言功能，玩家点进去能听角色的语音留言”，听起来不就是放个音频、加个列表吗？真正动手以后，你才会发现要处理的细节远比想象中多：音频是预加载还是按需加载？播放状态怎么管理？暂停、快进、断点续播怎么做？多人留言的高并发访问扛不扛得住？

我最近在梳理一个偶像养成主题的网页游戏功能时，就遇到了这样一个“电话留言合集”的需求。这个功能在页游里非常常见：玩家进入某个界面，能看到不同角色留下的语音留言，点击即可播放。整个功能涉及前端播放器、语音资源管理、用户播放记录、后台留言管理等多层内容。本文就以此为切入点，从零开始拆解一个网页游戏内“电话留言系统”的实现方案。

这篇文章适合三类读者：一是正在做页游或者 H5 小游戏，遇到了类似语音播放需求的前端开发；二是想了解音频资源在浏览器端如何高效管理、播放状态如何设计的初中级工程师；三是负责游戏功能模块设计的产品或技术负责人，需要预估这类功能的开发量和技术难点。

1. 这篇文章真正要解决的问题

先说结论：“电话留言合集”不是一个简单的音频列表页，它是一个完整的“音频资源 + 状态机 + 交互体验 + 数据记录”组合功能。

如果只看功能描述，很多人第一反应是：用 HTML 的<audio>标签循环播放不就行了？确实，如果只有一个音频，那这么做没有任何问题。但是当场景换成“全员留言”时，事情就变了：

• 角色数量多，音频文件多，全部预加载会浪费带宽，全部懒加载又会造成播放延迟。
• 每个留言有独立的封面、标题、时长、播放状态，播放器需要维护一个状态机。
• 玩家可能听了 30 秒就切走，下次回来要能记住播放进度。
• 游戏内通常还有剧情解锁条件，不是所有留言一开始就对玩家开放。
• 后端要记录哪些留言被播放过，用于任务奖励或者成就系统。

这些需求加在一起，已经远远超出“放个音频”的范畴。所以在动手写代码前，先把这个功能拆清楚，比什么都重要。

2. 电话留言系统的核心概念与模块划分

2.1 什么是“电话留言系统”

从产品形态上看，电话留言系统模拟的是现实中“语音信箱”的体验：某个角色在特定时间点给玩家打来电话，玩家没有接到，于是留下了一段语音。玩家上线后可以在留言界面看到这条语音，点击即可播放。

从技术实现上看，它包含以下四个核心模块：

模块	职责	关键技术点
音频资源管理	存储和管理所有留言音频	文件格式、加载策略、缓存机制
播放器状态机	控制播放、暂停、停止、切换	状态流转、事件监听、异常处理
留言列表交互	展示留言卡片、解锁状态、播放入口	列表渲染、条件判断、样式管理
播放数据记录	记录播放进度、播放次数、完成状态	本地存储、后端接口、同步策略

换一种更容易理解的说法：音频资源管理管的是“音频文件放哪、怎么取”；播放器状态机管的是“当前正在播哪一条、停在哪一秒”；留言列表交互管的是“玩家看到什么、点哪里”；播放数据记录管的是“玩家听过哪些、听到哪里了”。

2.2 为什么状态机是核心难点

音频播放最容易出错的地方，不是音频本身，而是“状态切换”。

一个简单的播放状态机至少包含五态：

空闲 -> 加载中 -> 播放中 -> 暂停 -> 播放中 ↓ 加载失败

每一次用户点击，都可能引发状态迁移。如果状态设计得不够清晰，就会出现“明明点了暂停，声音还在播”“播放完一条后列表状态没有复位”“拖进度条时时间显示错乱”这类问题。

所以，在写任何业务代码之前，应该先定义一个全局的播放器状态对象，把状态设计和 UI 解耦。这一点会贯穿本文后续的所有代码。

2.3 为什么不能只用<audio>标签叠加

有人会问：每个留言卡片放一个<audio>标签，不也能实现吗？能，但会出现三个问题：

1. 资源重复加载：页面里如果有 20 条留言，就会创建 20 个音频对象，内存开销明显。
2. 状态不同步：多个音频实例同时存在时，很难保证“播放 A 时自动停掉 B”。
3. 控制逻辑分散：播放、暂停、进度更新逻辑分散在各个卡片组件里，后期维护成本很高。

所以，更合理的做法是全局只维护一个Audio实例，通过不同的数据源切换来实现不同留言的播放。这就是“单例播放器”模式。

3. 技术选型与环境准备

本文的示例采用纯前端技术栈，不需要引入前端框架，这样任何基础的前端开发者都可以完整跑通。如果你想把代码迁移到 Vue 或 React 项目里，核心逻辑同样适用。

3.1 运行环境

• 操作系统：Windows / macOS / Linux 均可
• 浏览器：Chrome、Edge、Firefox 等现代浏览器
• 本地服务：推荐使用VSCode的Live Server插件，或者任意静态文件服务器

3.2 项目结构

phone-message-demo/ ├── index.html ├── css/ │ └── style.css ├── js/ │ ├── data.js │ ├── player.js │ └── main.js └── audio/ ├── character_01.mp3 ├── character_02.mp3 └── character_03.mp3

这个结构划分得很清晰：data.js负责模拟留言数据，player.js封装播放器核心逻辑，main.js负责渲染列表和绑定事件。

3.3 本地运行方式

如果你安装了 Node.js，可以在项目根目录执行：

npx serve .

如果没有 Node.js，也可以在 VSCode 中右键index.html，选择“Open with Live Server”。

4. 核心流程拆解

整个功能的实现流程可以拆成五个步骤。

4.1 定义留言数据结构

每条留言应该包含哪些字段？我建议至少包含：

{ id: '001', character: '角色A', title: '傍晚的一通电话', cover: './images/a_cover.png', audioSrc: './audio/character_01.mp3', duration: 46, locked: false, played: false }

其中locked表示是否解锁，played表示是否已经播放过，用来驱动小红点或者任务进度提示。

4.2 设计播放状态机

在player.js中维护一个全局状态：

const playerState = { status: 'idle', // idle | loading | playing | paused | error currentId: null, currentTime: 0, duration: 0 };

播放流程是：点击留言卡片 -> 将currentId设置为该留言 id -> 调用播放器load音频 -> 等待canplay事件 -> 调用play()-> 状态变为playing。

4.3 列表渲染

列表渲染要区分“已解锁”和“未解锁”两种状态。未解锁的留言卡片点击后应该弹提示，而不是尝试播放。

4.4 播放器交互

播放器的 UI 包括封面图、标题、进度条、播放/暂停按钮、时间显示。交互上要做到：点击卡片打开播放器，点击进度条跳转播放，播放结束后自动播放下一条，或者自动关闭并更新played状态。

4.5 记录播放数据

播放数据先存在localStorage中，后续接入后端时再把数据同步上去。这样游戏上线初期即使没有后端接口，功能也能正常演示。

5. 完整示例代码实现

5.1 留言数据文件：js/data.js

// 文件路径：js/data.js const messageData = [ { id: '001', character: '林小满', title: '练习室关门前的留言', cover: './images/cover_01.png', audioSrc: './audio/character_01.mp3', duration: 45, locked: false, played: false }, { id: '002', character: '周可欣', title: '深夜便利店偶遇后', cover: './images/cover_02.png', audioSrc: './audio/character_02.mp3', duration: 38, locked: false, played: false }, { id: '003', character: '苏晚晴', title: '巡演前的最后叮嘱', cover: './images/cover_03.png', audioSrc: './audio/character_03.mp3', duration: 52, locked: true, played: false } ];

locked: true表示该留言默认未解锁，需要满足解锁条件后才可播放。

5.2 播放器核心封装：js/player.js

// 文件路径：js/player.js const playerState = { status: 'idle', currentId: null, currentTime: 0, duration: 0 }; const audio = new Audio(); function resetState() { playerState.status = 'idle'; playerState.currentId = null; playerState.currentTime = 0; playerState.duration = 0; } function loadMessage(message) { return new Promise((resolve, reject) => { playerState.status = 'loading'; playerState.currentId = message.id; audio.src = message.audioSrc; audio.load(); const onCanPlay = () => { audio.removeEventListener('canplay', onCanPlay); playerState.duration = audio.duration || message.duration; resolve(); }; const onError = () => { audio.removeEventListener('error', onError); playerState.status = 'error'; reject(new Error('音频加载失败: ' + message.audioSrc)); }; audio.addEventListener('canplay', onCanPlay); audio.addEventListener('error', onError); }); } function playMessage(message) { if (playerState.currentId === message.id && playerState.status === 'paused') { audio.play(); playerState.status = 'playing'; return; } loadMessage(message) .then(() => { audio.play(); playerState.status = 'playing'; message.played = true; updatePlayedState(message.id); }) .catch((error) => { console.error(error); }); } function pauseMessage() { audio.pause(); playerState.status = 'paused'; playerState.currentTime = audio.currentTime; } function stopMessage() { audio.pause(); audio.currentTime = 0; resetState(); } audio.addEventListener('timeupdate', () => { if (playerState.status === 'playing') { playerState.currentTime = audio.currentTime; if (typeof onTimeUpdate === 'function') { onTimeUpdate(audio.currentTime, audio.duration || playerState.duration); } } }); audio.addEventListener('ended', () => { if (typeof onMessageEnded === 'function') { onMessageEnded(playerState.currentId); } resetState(); });

上面这段代码里有一个很容易被忽略的设计：endMessage处理完后调用了resetState()，这样播放器在一条留言播放结束后会回到空闲状态，列表 UI 才能正确复位。

5.3 页面结构：index.html

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>电话留言合集 - 页游演示</title> <link rel="stylesheet" href="./css/style.css"> </head> <body> <div class="container"> <h1>偶像们的电话留言合集</h1> <p class="subtitle">点击卡片播放留言，每人一条，共计 3 条</p> <div id="messageList" class="message-list"></div> </div> <!-- 播放器抽屉 --> <div id="playerPanel" class="player-panel hidden"> <div class="player-cover"> <img id="playerCover" src="" alt="cover"> </div> <div class="player-info"> <div id="playerTitle" class="player-title">尚未选择留言</div> <div id="playerCharacter" class="player-character"></div> </div> <div class="player-progress"> <span id="currentTime">00:00</span> <input id="progressBar" type="range" min="0" max="100" value="0"> <span id="totalTime">00:00</span> </div> <div class="player-controls"> <button id="playBtn" class="btn-play">播放</button> <button id="closeBtn" class="btn-close">关闭</button> </div> </div> <script src="./js/data.js"></script> <script src="./js/player.js"></script> <script src="./js/main.js"></script> </body> </html>

这里把播放器放在一个抽屉面板div中，默认隐藏。用户点击卡片后，面板弹出并加载对应音频。

5.4 页面交互逻辑：js/main.js

// 文件路径：js/main.js const listContainer = document.getElementById('messageList'); const playerPanel = document.getElementById('playerPanel'); const playerCover = document.getElementById('playerCover'); const playerTitle = document.getElementById('playerTitle'); const playerCharacter = document.getElementById('playerCharacter'); const currentTimeSpan = document.getElementById('currentTime'); const totalTimeSpan = document.getElementById('totalTime'); const progressBar = document.getElementById('progressBar'); const playBtn = document.getElementById('playBtn'); const closeBtn = document.getElementById('closeBtn'); function formatTime(seconds) { if (isNaN(seconds)) return '00:00'; const min = Math.floor(seconds / 60); const sec = Math.floor(seconds % 60); return `${String(min).padStart(2, '0')}:${String(sec).padStart(2, '0')}`; } function renderList() { listContainer.innerHTML = ''; messageData.forEach((message) => { const card = document.createElement('div'); card.className = 'message-card'; if (message.locked) { card.classList.add('locked'); } if (message.played) { card.classList.add('played'); } const statusText = message.locked ? '未解锁' : (message.played ? '已收听' : '未收听'); card.innerHTML = ` <div class="card-cover"> <img src="${message.cover}" alt="${message.character}"> </div> <div class="card-info"> <div class="card-character">${message.character}</div> <div class="card-title">${message.title}</div> <div class="card-meta">${statusText} · ${formatTime(message.duration)}</div> </div> `; card.addEventListener('click', () => { if (message.locked) { alert('这条留言还没有解锁'); return; } openPlayer(message); playMessage(message); }); listContainer.appendChild(card); }); } function openPlayer(message) { playerPanel.classList.remove('hidden'); playerCover.src = message.cover; playerTitle.textContent = message.title; playerCharacter.textContent = message.character; totalTimeSpan.textContent = formatTime(message.duration); currentTimeSpan.textContent = '00:00'; progressBar.value = 0; playBtn.textContent = '暂停'; } function updateProgress(current, duration) { currentTimeSpan.textContent = formatTime(current); if (duration) { progressBar.value = (current / duration) * 100; } } window.onTimeUpdate = updateProgress; window.onMessageEnded = (id) => { playBtn.textContent = '播放'; progressBar.value = 0; currentTimeSpan.textContent = '00:00'; closePlayer(); }; function closePlayer() { stopMessage(); playerPanel.classList.add('hidden'); } playBtn.addEventListener('click', () => { const currentMessage = messageData.find((m) => m.id === playerState.currentId); if (!currentMessage) return; if (playerState.status === 'playing') { pauseMessage(); playBtn.textContent = '继续'; } else if (playerState.status === 'paused' || playerState.status === 'idle') { playMessage(currentMessage); playBtn.textContent = '暂停'; } }); closeBtn.addEventListener('click', closePlayer); progressBar.addEventListener('input', () => { if (!playerState.duration) return; const targetTime = (progressBar.value / 100) * playerState.duration; audio.currentTime = targetTime; currentTimeSpan.textContent = formatTime(targetTime); }); function updatePlayedState(id) { const message = messageData.find((m) => m.id === id); if (message) { message.played = true; } savePlayedRecords(); renderList(); } function savePlayedRecords() { const playedIds = messageData .filter((m) => m.played) .map((m) => m.id); localStorage.setItem('phone_message_played', JSON.stringify(playedIds)); } function loadPlayedRecords() { const stored = localStorage.getItem('phone_message_played'); if (!stored) return; const playedIds = JSON.parse(stored); messageData.forEach((m) => { if (playedIds.includes(m.id)) { m.played = true; } }); } loadPlayedRecords(); renderList();

这段代码把前面定义的数据结构、播放器封装和 DOM 操作串起来了。核心逻辑是：点击卡片 -> 打开播放器 ->playMessage()加载并播放 -> 更新played状态 -> 写入localStorage。

5.5 样式文件：css/style.css

样式不是本文重点，但为了让功能可以直观演示，给出一份简洁可用的样式：

/* 文件路径：css/style.css */ * { box-sizing: border-box; margin: 0; padding: 0; } body { font-family: 'PingFang SC', 'Microsoft YaHei', sans-serif; background: #f5f0fa; min-height: 100vh; } .container { max-width: 640px; margin: 0 auto; padding: 32px 16px; } h1 { font-size: 24px; color: #2e2a33; margin-bottom: 8px; } .subtitle { color: #888; font-size: 14px; margin-bottom: 24px; } .message-list { display: flex; flex-direction: column; gap: 16px; } .message-card { display: flex; align-items: center; background: #fff; border-radius: 12px; padding: 12px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06); cursor: pointer; transition: transform 0.2s ease, box-shadow 0.2s ease; } .message-card:hover { transform: translateY(-2px); box-shadow: 0 6px 16px rgba(0, 0, 0, 0.1); } .message-card.locked { opacity: 0.6; cursor: not-allowed; } .message-card.played .card-meta { color: #9c7bd8; } .card-cover { width: 64px; height: 64px; border-radius: 8px; overflow: hidden; flex-shrink: 0; margin-right: 12px; } .card-cover img { width: 100%; height: 100%; object-fit: cover; } .card-info { flex: 1; } .card-character { font-weight: 600; font-size: 16px; color: #2e2a33; } .card-title { color: #666; font-size: 14px; margin: 4px 0; } .card-meta { color: #aaa; font-size: 12px; } .player-panel { position: fixed; bottom: 0; left: 0; right: 0; background: #fff; border-radius: 16px 16px 0 0; box-shadow: 0 -4px 20px rgba(0, 0, 0, 0.12); padding: 20px 16px 24px; max-width: 640px; margin: 0 auto; } .player-panel.hidden { display: none; } .player-cover { text-align: center; margin-bottom: 12px; } .player-cover img { width: 180px; height: 180px; border-radius: 12px; object-fit: cover; } .player-info { text-align: center; } .player-title { font-size: 18px; font-weight: 600; color: #2e2a33; } .player-character { color: #888; font-size: 14px; margin-top: 4px; } .player-progress { display: flex; align-items: center; gap: 12px; margin: 20px 0 12px; color: #888; font-size: 12px; } .player-progress input[type="range"] { flex: 1; } .player-controls { display: flex; justify-content: center; gap: 16px; } .btn-play, .btn-close { border: none; border-radius: 20px; padding: 10px 24px; font-size: 14px; cursor: pointer; } .btn-play { background: #9c7bd8; color: #fff; } .btn-close { background: #f0edf5; color: #555; }

6. 运行结果与效果验证

完成上述文件和代码后，在本地启动服务，打开浏览器访问index.html，预期效果如下：

• 页面顶部显示标题“偶像们的电话留言合集”。
• 页面中展示三张留言卡片，前两张可点击，第三张显示“未解锁”。
• 点击第一张卡片，底部弹出播放器面板，封面加载，音频开始播放。
• 播放按钮可以在“播放 / 暂停 / 继续”之间切换。
• 拖动进度条可以跳转到指定时间。
• 播放结束后，播放器自动关闭，卡片的“未收听”状态变成“已收听”。
• 刷新页面后，已播放状态仍然保持，说明localStorage生效。

验证是否成功的判断标准是：

1. 音频能正常播放且声音清晰，没有明显卡顿。
2. 播放过程中点击其他卡片，播放源能正确切换。
3. 播放结束后状态能正确复位，不会出现“播放按钮还是暂停”的情况。
4. 解锁条件判断有效，未解锁卡片点击后不会加载音频。

如果播放过程中发现问题，优先检查浏览器控制台的报错信息，以及音频文件的路径是否大小写一致、文件名是否正确。

7. 常见问题与排查思路

问题现象	可能原因	排查方式	解决方案
点击卡片没有声音	音频文件路径错误或格式不支持	打开浏览器控制台查看网络请求	检查audioSrc路径，确认音频文件存在且格式为 MP3 或 Ogg
播放完一条后状态没有复位	播放器没有监听ended事件	在控制台打印playerState.status	在ended事件中调用resetState()
点 A 留言，B 留言也在播放	页面中创建了多个 Audio 实例	全局搜索new Audio()排查	改为全局单例 Audio 实例
未解锁卡片仍能播放	点击事件没有判断 locked 字段	查看代码中 locked 判断逻辑	在点击事件开头增加 locked 判断并 return
进度条拖动后时间显示错乱	进度条 input 事件未同步到 audio.currentTime	检查 progressBar 事件监听	在 input 事件中设置audio.currentTime
刷新后播放状态丢失	未使用 localStorage 或存储 key 不一致	查看代码中 savePlayedRecords 和 loadPlayedRecords	确保存储读取使用同一个 key
音频加载非常慢	所有音频都在页面初始化时预加载	在 Network 面板查看加载时机	改为按需加载，播放时再设置 audio.src

这里最值得强调的是第二条：播放状态复位。在实际项目里，这个 bug 最容易出现在“播放播完”的瞬间，因为ended事件在移动端浏览器上偶发延迟，如果代码里没有做兜底处理，UI 会长期停留在播放状态。

8. 最佳实践与工程建议

8.1 音频资源管理建议

音频文件属于体积较大的静态资源，建议放到 CDN 或者对象存储中，而不是和前端代码混在一起。文件名要使用语义化命名，比如message_001_linxiaoman.mp3，不要使用无规则的一串随机字符。

如果角色多、留言多，还要建立一份资源清单表，由后端接口下发，而不是写死在前端。这样运营同学不用改代码就能新增留言。

8.2 播放记录走后端接口

前文的localStorage方案适合做演示和单机原型。正式上线时，播放记录应该同步到后端，用于任务系统、成就系统、防重复奖励等需求。

建议接口设计如下：

POST /api/v1/user/message/play { "messageId": "001", "playedDuration": 20, "finished": false }

后端在写接口时，要注意重复提交的问题。玩家播放到一半退出再进来，可能多次上报同一个messageId，建议用messageId做唯一约束，服务端做幂等处理。

8.3 状态机设计要提前考虑恢复场景

真实游戏场景里，用户会频繁切换页面、切后台、锁屏。移动端浏览器切到后台后，音频会被系统自动暂停，此时播放器的状态必须从playing切回paused。建议监听visibilitychange事件：

document.addEventListener('visibilitychange', () => { if (document.hidden && playerState.status === 'playing') { pauseMessage(); } });

8.4 解锁条件的处理

留言解锁不能只靠前端locked字段挡住 UI，后端接口也要做权限校验。玩家请求音频地址时，后端需要校验玩家是否满足解锁条件，否则即使前端不拦截，玩家通过拼接 URL 也能拿到音频。

8.5 统一错误提示

音频加载失败时，不要只在控制台打印错误。玩家看到的是“点击没反应”，这是最差的体验。建议在 UI 上增加 Toast 提示，并保留重试按钮。如果某个角色的音频文件缺失，后端可以下发一个兜底音频地址，或者前端直接使用全服通用的占位音频。

8.6 真机测试不能省

音频播放在 PC 浏览器和移动端浏览器表现差异很大，尤其要注意移动端的自动播放限制。浏览器通常不允许页面加载后直接自动播放音频，必须由用户主动触发play()。如果遇到“自动播放被拦截”的情况，不要试图绕过浏览器限制，应该引导用户点击播放按钮，等待用户手势后再执行播放操作。

8.7 代码版本和接口兼容

如果游戏已经上线，老的客户端可能还在使用旧的留言接口。后端在调整字段时，要保留旧字段的兼容返回，或者通过版本号控制返回结构。前端的serverVersion字段建议从接口动态获取，不要写死在代码里。

9. 总结与后续学习方向

本文以“偶像们的电话留言合集”这个页游功能为场景，完整梳理了从数据结构、播放器状态机、列表渲染到播放记录存储的整个实现链路。核心收获有三点：

第一，电话留言系统不是一个单纯的音频播放页面，而是“音频资源、状态机、UI 交互、数据记录”四层结构的组合功能，开发前要先把模块边界划清楚。

第二，播放器的状态设计决定了整个功能的上限。单例 Audio 实例、五态状态机、ended事件复位这三个要点如果能落实到代码里，就可以避免大量线上问题。

第三，前端实现只是第一步，生产环境还需要考虑后端权限校验、资源走 CDN、播放记录幂等上报、移动端切后台暂停等工程化问题。

如果你接下来想继续深入，可以从几个方向展开：一是把播放器迁移到 Vue 3 或 React 项目里，用组件化方式重构；二是调研 Web Audio API 的可视化频谱效果，给留言播放器增加音频动效；三是把当前的前端模拟数据部分替换成真实接口，接上用户系统、任务系统和统计系统。

这个功能的开发难度并不高，但细节非常多。建议把本文的代码保留到本地，按照自己的项目场景改一版，跑通之后你会对浏览器音频播放的整个机制有更深的理解。