webview_flutter加载页iOS正常Android白屏问题解决方案

算力阿峰

2026-8-29

问题产生原因

同一份代码iOS端正常、Android端WebView显示空白，是以下几个Android端特有机制导致的：

渲染实现兼容性问题：代码中手动指定WebView.platform = AndroidWebView()，该实现基于旧版虚拟显示方案，在Android 10及以上版本、部分厂商定制ROM上存在渲染层级bug，会导致WebView区域透明、内容不渲染，代码中被注释的SurfaceAndroidWebView()才是官方推荐的、基于SurfaceView的稳定渲染实现。
系统加载限制：从Android 9（API 28）开始，系统默认禁止WebView加载HTTP明文资源，若传入的业务地址为HTTP、或目标HTTPS页面内嵌HTTP的脚本/图片资源，WebView会直接拦截加载且无明显弹窗报错，最终呈现空白页。
格式支持差异：代码加载的目标资源是PDF格式报表，iOS端WebView内置了PDF渲染能力，Android原生WebView本身无内置PDF解析支持，拿到PDF文件流后无法直接渲染，这是两端表现不一致的核心原因之一。
配置缺失：未给应用声明网络权限、未开启WebView的JS/本地存储访问权限，也会导致资源加载失败。
加载状态逻辑错误：代码中IndexedStack的index固定为0，WebView初始化、资源加载过程中会直接显示空白区域，预先写好的加载中指示器完全不会触发显示。

修复方案

按以下步骤逐一调整即可解决问题：

替换Android端WebView渲染实现
修改initState中的渲染配置，改用Surface渲染方案：

@override
void initState() {
  super.initState();
  if (Platform.isAndroid) {
    WebView.platform = SurfaceAndroidWebView();
  }
}

补全Android工程配置
打开项目路径下的android/app/src/main/AndroidManifest.xml文件：

在<manifest>根节点下添加网络权限声明：

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

在<application>节点上添加明文流量允许配置，适配可能存在的HTTP接口请求：

<application
  android:usesCleartextTraffic="true"
  <!-- 保留原有其他配置项 -->
>

解决Android端WebView不支持PDF加载的问题
根据业务场景二选一即可：

若使用3.0及以上版本的webview_flutter，可搭配官方Android端扩展开启内置PDF渲染支持；
公网环境下可借助公共PDF在线预览服务包装原PDF地址后交给WebView加载；内网环境下建议引入原生PDF渲染插件，先将PDF文件下载到应用本地临时目录，再用原生PDF组件展示，兼容性比WebView加载更稳定。

修复加载状态逻辑
新增加载状态标记，控制IndexedStack在加载过程中显示进度组件，加载完成后再显示WebView，同时添加错误回调方便定位问题：

// 新增状态变量
bool _isLoading = true;

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      leading: IconButton(
        icon: Icon(Icons.arrow_back_ios),
        iconSize: 20.0,
        onPressed: () {
          Navigator.pop(context);
        },
      ),
      centerTitle: true,
      title: Text('Report')),
    body: IndexedStack(
      index: _isLoading ? 1 : 0,
      children: [
        Column(
          children: <Widget>[
            Expanded(
                child: WebView(
              javascriptMode: JavascriptMode.unrestricted,
              onPageStarted: (url) {
                setState(() {
                  _isLoading = true;
                });
              },
              onWebViewCreated: (WebViewController webViewController) {
                Map<String, String> headers = {"Cmdbuild-authorization": widget.token};
                webViewController.loadUrl(
                    widget.url +
                        "/services/rest/v3/reports/286763/Activity%20report.pdf?extension=pdf&parameters=%7B%22ProcessId%22%3A" +
                        widget.man.id.toString() +
                        "%7D",
                    headers: headers);
              },
              onPageFinished: (url) {
                setState(() {
                  _isLoading = false;
                });
              },
              onWebResourceError: (error) {
                // 调试阶段可在此打印错误日志，快速定位加载失败原因
                debugPrint("WebView加载错误: ${error.description}, 错误码: ${error.errorCode}");
              },
            )),
          ],
        ),
        Container(
          color: Colors.white,
          child: Center(
            child: CircularProgressIndicator(),
          ),
        ),
      ],
    ));
}

混合内容适配（可选）
如果目标页面存在HTTP和HTTPS混合资源，可在WebView创建后通过JS注入放开CSP限制，避免资源被拦截。

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