NotAllowedError — 自动播放被浏览器策略阻止

症状

本篇指南处理“NotAllowedError — 自动播放被浏览器策略阻止”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。

可观察到的症状包括：

• 未捕获的 DOMException: play() 失败，因用户未先与文档交互
• 媒体元素在页面加载时不播放
• 点击后音频可用，但无法自动播放

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

document.querySelector('video').play().catch(e => console.log(e.name, e.message))

NotAllowedError 且提示需要交互，即确认是自动播放策略而非源错误。

步骤 2

video.muted = true; video.play().catch(console.error)

静音自动播放普遍被允许，先静音启动可区分策略问题与媒体错误。

常见诱因（按出现频率排序）：

• 浏览器要求先有用户手势才允许非静音播放
• 自动播放策略阻止该源的有声音媒体
• 在用户交互前调用了 play()

根因

为保护用户，浏览器阻止有声音的自动播放。在用户与文档交互或媒体静音前，play() 返回以 NotAllowedError 拒绝的 promise。

修复

先静音启动并允许用户取消静音，在 click/keypress 处理器内调用 play()，并始终捕获 play() 的 promise，以展示播放控件而非未捕获拒绝。

注意：无手势地反复重试 play() 会持续拒绝并刷屏日志；应改为响应手势。

const video = document.querySelector('video');
video.muted = true; // allowed to autoplay when muted
try {
  await video.play();
} catch (err) {
  if (err.name === 'NotAllowedError') {
    showPlayButton(); // require a user gesture
  } else {
    console.error(err);
  }
}

// or start from a gesture
playButton.addEventListener('click', () => {
  video.muted = false;
  video.play().catch(console.error);
});

验证

加载页面并确认静音播放启动；点击取消静音并确认音频播放且无未捕获错误。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。