audio标签必须添加controls属性才能显示播放控件，否则即使音频加载成功也无法交互；需用多格式source回退并正确声明type；autoplay仅配合muted可能生效，可靠方案是用户首次点击后JS调用play()。
audio 标签不加 controls 就等于没放
用户看不到播放控件，就无法点击、拖动、调节音量，哪怕音频文件已加载成功，页面也“静音”得毫无存在感。这不是 bug，是设计逻辑：HTML5 的 audio 默认不暴露任何 UI，必须显式声明 controls 属性才能激活交互界面。
常见错误现象包括：
- 写了
<audio src="bgm.mp3"></audio>，但页面干干净净，什么也不显示 - 控制台无报错，Network 面板能看到音频请求 200，但就是点不了——因为没加
controls - 误以为
muted或autoplay能替代controls，结果两者都加了，还是没按钮
真正能立刻生效的最小结构是：<audio src="./audio/bgm.mp3" controls></audio>。路径必须是相对（如 "./audio/bgm.mp3"）或绝对 URL（如 "https://cdn.example.com/bgm.ogg"），不能是 "bgm.mp3" 这种裸文件名，也不能是 file:/// 协议路径（本地双击打开时 Chrome/Firefox 会直接拒绝加载）。
MP3 单格式回退在 Firefox 和 Safari 上大概率失效
只放一个 .mp3 文件，等于主动放弃部分用户。Firefox 默认不支持 MP3 解码；Safari 对 OGG/Opus 更友好；iOS Safari 甚至对某些 MP3 编码（如 VBR）有兼容问题。浏览器不会报错，而是静默跳过该 <source></source>，最终显示“无法加载媒体”或空控件。
立即学习“前端免费学习笔记（深入）”；
正确做法是用 <source></source> 提供多格式回退：
<audio controls> <source src="bgm.mp3" type="audio/mpeg"> <source src="bgm.ogg" type="audio/ogg"> 您的浏览器不支持 audio 元素。 </audio>
注意三点：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
-
type属性不能省，且必须写标准 MIME 类型："audio/mpeg"（不是"audio/mp3"），"audio/ogg"（不是"audio/oga"） - 顺序很重要：浏览器按
<source></source>出现顺序尝试，第一个能解码且可访问的就停，后续忽略 -
.ogg推荐用ffmpeg -i bgm.mp3 -c:a libvorbis bgm.ogg转，免费、体积小、兼容稳
autoplay + muted 是唯一可能触发自动播放的组合
现代浏览器（Chrome 94+、Firefox、Safari）默认禁止「有声自动播放」，这是策略性限制，不是 bug。单独加 autoplay 基本无效；加 autoplay muted 有可能成功（尤其在移动端），但背景音乐没声音等于白搭。
如果你真需要用户无感启动背景音，唯一可靠路径是：先让用户点一下（任意位置或按钮），再 JS 调用 play() 并解除静音：
<button id="start-bgm">▶ 开启背景音乐</button> <audio id="bgm" loop> <source src="bgm.mp3" type="audio/mpeg"> <source src="bgm.ogg" type="audio/ogg"> </audio>
对应脚本：
const audio = document.getElementById('bgm');
const btn = document.getElementById('start-bgm');
btn.addEventListener('click', () => {
audio.play()
.then(() => {
audio.muted = false;
audio.volume = 0.3;
})
.catch(e => console.warn('播放失败:', e.message));
btn.style.display = 'none';
});
关键细节：
- 必须在
click或touchstart回调里调play()，不能放在DOMContentLoaded或setTimeout中 -
play()返回 Promise，务必.catch()，否则错误静默，调试困难 - iOS Safari 最严格：首次交互后才解锁音频能力，之后页面内跳转（如 hash 变化）仍可继续播放，但跨 HTML 页面会重置
跨页面连续播放背景音只能靠 iframe 或单页架构
多页 HTML 游戏或网站中，从 scene1.html 跳到 scene2.html，浏览器会销毁旧文档、加载新文档，audio 元素必然中断重播。CSS 或 JS 无法绕过这个生命周期。
可行方案只有两个：
- 把所有游戏内容嵌在
<iframe src="scene1.html"></iframe>里，主页面（parent）持有一个独立的<audio></audio>，由 parent 控制播放，子页面仅发消息通信 - 改造成单页应用（SPA），用 JS 动态替换 DOM 内容，不刷新整个页面，
audio实例持续存活
别指望 localStorage 记录播放时间然后手动 seek —— 音频已中断，seek 无效；也别依赖 preload="auto"，它只影响资源加载时机，不改变播放策略。
