Android端webview_flutter无法加载文件：白屏及updateAcquireFence报错

针对你使用webview_flutter开发时，iOS端正常加载文件但Android端白屏并出现updateAcquireFence: Did not find frame报错的问题，可按以下步骤排查解决：

1. 修正文件Uri的生成方式 #

Android WebView对本地文件路径的解析要求更严格，避免直接用字符串拼接Uri，改用Uri.file()方法生成标准的文件Uri，同时添加错误捕获回调排查具体问题：

@override
void initState() {
  _delegate = NavigationDelegate(
    onPageFinished: (_) => setState(() {
      _isLoading = false;
    }),
    onWebResourceError: (error) {
      print('加载错误: 错误码${error.errorCode}，描述${error.description}');
    },
  );
  _controller = WebViewController();

  final fileUri = Uri.file(widget.file.url);
  _controller
    ..setNavigationDelegate(_delegate)
    ..setJavaScriptMode(JavaScriptMode.unrestricted)
    ..loadRequest(fileUri);

  super.initState();
}

2. 配置Android端必要权限与WebView设置 #

• 添加存储权限：在android/app/src/main/AndroidManifest.xml中添加权限声明（若文件位于外部存储）：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<!-- Android 13+ 可替换为READ_MEDIA_IMAGES等细分权限 -->

针对Android 10及以上版本，在<application>标签中添加兼容配置：

<application
  ...
  android:requestLegacyExternalStorage="true">

• 开启WebView文件访问权限：在WebViewController中启用文件访问相关设置：

_controller.setSettings(const WebSettings(
  allowFileAccess: true,
  allowContentAccess: true,
));

3. 验证文件的存在性与可访问性 #

在加载前检查文件是否存在，避免因路径错误导致加载失败：

@override
void initState() {
  super.initState();
  _checkAndLoadFile();
}

Future<void> _checkAndLoadFile() async {
  final targetFile = File(widget.file.url);
  if (await targetFile.exists()) {
    _delegate = NavigationDelegate(
      onPageFinished: (_) => setState(() {
        _isLoading = false;
      }),
      onWebResourceError: (error) {
        print('加载错误: 错误码${error.errorCode}，描述${error.description}');
      },
    );
    _controller = WebViewController();
    _controller
      ..setNavigationDelegate(_delegate)
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setSettings(const WebSettings(
        allowFileAccess: true,
        allowContentAccess: true,
      ))
      ..loadRequest(Uri.file(targetFile.path));
  } else {
    print('目标文件不存在: ${widget.file.url}');
    // 可添加文件不存在的UI提示逻辑
  }
}

4. 排查updateAcquireFence报错的根源 #

该报错属于WebView渲染层的警告，本质是文件加载失败引发的渲染异常。通过onWebResourceError回调捕获的具体错误信息（如权限不足、文件格式不支持），可以快速定位核心问题。

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