Android WebView无法播放HTML5视频，求排查与解决方案

核心排查点与修复步骤 #

1. 补全WebChromeClient的全屏回调实现 #

WebView播放HTML5视频必须依赖WebChromeClient处理全屏切换逻辑，缺失关键回调会导致视频无法正常渲染：

binding.webView.webChromeClient = object : WebChromeClient() {
    private var customView: View? = null
    private var customViewCallback: WebChromeClient.CustomViewCallback? = null

    override fun onShowCustomView(view: View, callback: WebChromeClient.CustomViewCallback) {
        customView = view
        customViewCallback = callback
        // 切换到全屏：隐藏WebView，将视频视图添加到布局
        binding.webView.visibility = View.GONE
        (binding.root as ViewGroup).addView(view)
        view.visibility = View.VISIBLE
    }

    override fun onHideCustomView() {
        // 恢复原布局：移除视频视图，显示WebView
        customView?.let {
            (binding.root as ViewGroup).removeView(it)
            it.visibility = View.GONE
        }
        customViewCallback?.onCustomViewHidden()
        binding.webView.visibility = View.VISIBLE
        customView = null
        customViewCallback = null
    }
}

2. 在Activity级别启用硬件加速 #

仅给WebView设置LAYER_TYPE_HARDWARE可能不够，需在AndroidManifest.xml的对应Activity标签中全局开启：

<activity
    android:name=".YourWebViewActivity"
    android:hardwareAccelerated="true">
</activity>

注：API 18以下的低版本设备对硬件加速支持有限，可尝试关闭测试，但高版本建议保持开启。

3. 允许混合内容（Android 9+） #

如果网站是HTTPS协议，但视频源为HTTP，Android 9（API 28）及以上默认禁止混合内容加载，需手动开启：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    settings.mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW
}

4. 适配网站的User-Agent检测 #

部分视频网站会根据User-Agent限制播放权限，可将WebView的UA设置为主流移动端浏览器的标识：

settings.userAgentString = "Mozilla/5.0 (Linux; Android 13; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Mobile Safari/537.36"

5. 检查视频编码兼容性 #

通过Chrome开发者工具（开启WebView调试后可连接查看）确认视频编码：

• H.264是Android WebView通用支持格式，但需确保为Baseline/Main Profile；
• VP9在Android 7+支持，但低端设备可能存在兼容问题，可换设备测试或尝试切换视频源。

6. 调整缓存策略 #

当前设置LOAD_CACHE_ELSE_NETWORK可能导致旧缓存干扰播放，可临时改为默认缓存模式或清除缓存：

// 临时切换缓存模式
settings.cacheMode = WebSettings.LOAD_DEFAULT

// 清除WebView缓存（可选）
binding.webView.clearCache(true)
binding.webView.clearHistory()

7. 确认必要权限 #

确保AndroidManifest.xml中添加了网络权限：

<uses-permission android:name="android.permission.INTERNET" />

额外优化点 #

• 移除代码中重复的settings.allowFileAccess = true，避免冗余配置；
• 开启WebView调试模式，通过Chrome DevTools查看Console报错定位问题：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    WebView.setWebContentsDebuggingEnabled(true)
}

内容的提问来源于stack exchange，提问作者Ayan Mishra