video.requestFullscreen() 失败主因是浏览器兼容性、非用户手势触发或元素未挂载；全屏后黑屏需监听 fullscreenchange 并显式 play()；iOS Safari 需设 playsinline 和 webkit-playsinline 属性且禁用 JS 调用。
video 元素调用 requestFullscreen() 失败的常见报错
直接调用 video.requestFullscreen() 报 TypeError: requestFullscreen is not a function，大概率是浏览器兼容性或调用时机问题。Chrome 和 Edge 用的是 requestFullscreen()，但旧版需要加前缀：webkitRequestFullscreen()（Safari）、mozRequestFullScreen()（Firefox）。更关键的是：这个方法必须由用户手势（如 click、touchend）触发，否则会被浏览器静默拒绝，控制台可能只显示 Failed to execute 'requestFullscreen' on 'Element': API can only be initiated by a user gesture.。
实操建议：
- 优先使用标准方法
video.requestFullscreen()，再 fallback 到带前缀的版本 - 确保绑定在
click或touchend回调里，不要在setTimeout、Promise.then或load事件中直接调用 - 检查
video元素是否已挂载到 DOM —— 动态创建后未 append 就调用会报 “not attached” 类错误
全屏后视频黑屏/卡住/音画不同步
进入全屏后画面冻结、没声音、或播放器状态异常，通常不是全屏 API 本身的问题，而是浏览器对全屏状态下媒体行为的策略调整。比如 Safari 在全屏时会暂停 video 并清空 src；Chrome 某些版本会在全屏切换瞬间触发 pause 事件，而你的业务逻辑可能误判为用户主动暂停。
实操建议：
- 监听
fullscreenchange事件，在进入全屏后显式调用video.play()（注意捕获 Promise reject，比如因自动播放策略被拒） - 避免在
fullscreenchange中重复调用play()—— 进出全屏各触发一次，容易造成音频重叠或播放中断 - 若使用
object-fit: cover或 CSS transform 缩放视频，全屏后可能因尺寸重算导致渲染异常，可尝试在fullscreenchange后video.style.transform = 'none'重置
移动端 iOS Safari 全屏按钮不出现或点不动
iOS Safari 对 的全屏控制极其严格：只有设置 playsinline="false"（注意，iOS 10+ 实际需设为 playsinline="" 或不设）且同时满足 webkit-playsinline="false" 才允许唤起原生全屏控件。但即使这样，点击区域也仅限于系统提供的「全屏按钮」，无法用 JS 主动调用 requestFullscreen() —— 它会直接忽略。
实操建议：
- 在
标签上明确写playsinline属性（值为空或省略），并添加webkit-playsinline（同样为空） - 移除自定义全屏按钮的
click绑定，改用监听webkitbeginfullscreen/webkitendfullscreen事件做状态同步 - 不要依赖
document.fullscreenElement判断 iOS 全屏状态，它始终为null；改用document.webkitIsFullScreen
调试时如何快速确认当前全屏状态和触发源
靠肉眼看不出是 JS 调用失败，还是用户没点对位置，或是浏览器策略拦截。最有效的方式是把关键状态打出来，而不是只看控制台有没有报错。
实操建议：
- 在绑定全屏操作前，打印
video是否支持：video.requestFullscreen ? 'yes' : 'no' - 监听
document上的fullscreenerror事件，输出event.target和event.reason（Chrome 会提供具体原因字符串） - 用
chrome://flags/#enable-web-platform-tests开启实验性全屏调试标记（仅开发机），或在 DevTools Console 手动执行document.fullscreenElement确认当前元素
真正难处理的，是那些不报错但也不生效的情况——比如 video 被父容器 overflow: hidden 截断，或者 z-index 被遮挡导致点击穿透失败。这类问题不会出现在控制台，得靠 Elements 面板逐层检查样式和事件监听器。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
