Flutter中WebViewController的延迟初始化错误排查求助

开发者阿泽

2026-4-8

各位大佬好，我最近在开发Flutter WebView页面时遇到了一个头疼的问题：我用late修饰了WebViewController _controller;，但运行时一直提示延迟初始化错误，实在搞不懂哪里出问题了，麻烦帮忙看看我的代码，指点一下！

我的代码大致结构是这样的：在initState里调用异步方法setUpWebViewController()来初始化_controller，但运行时总是报错说_controller未初始化。下面是关键代码片段：

class WebViewPageState extends State<WebViewLogsPage> {
  static WebViewController? staticController;
  late WebViewController _controller;
  var loadingPercentage = 0;
  late final Future<void> _initialization;

  @override
  void initState() {
    super.initState();
    _initialization = setUpWebViewController();
    // 其他初始化逻辑...
  }

  Future<void> setUpWebViewController() async {
    // 异步获取URL等逻辑...
    String URL;
    String? domainAtLogin = await apd.getDomain();
    if (domainAtLogin != null) {
      URL = "https://$domainAtLogin.relaso.com/pHome";
    } else {
      URL = "https://relaso.com/pLogin";
    }
    
    _controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..loadRequest(Uri.parse(URL))
      ..setNavigationDelegate(...);
    setNavigation();
    WebViewPageState.staticController = _controller;
  }

  // 其他方法...

  @override
  Widget build(BuildContext context) {
    // 这里直接使用_controller的话，可能会因为_initialization还没完成导致错误
    return WebViewWidget(controller: _controller);
  }
}

我猜测可能是因为setUpWebViewController是异步方法，initState里只是启动了这个Future，但build方法会在initState之后立即执行，这时候_controller还没被赋值，所以触发了late初始化错误？

有没有大佬能帮我分析下具体原因，以及怎么解决这个问题呀？我试过调整初始化顺序，但还是没搞定。

可能的解决方案：

根据你的代码结构，问题确实出在异步初始化和Widget构建的时序上：_controller是late类型，必须在被访问前完成初始化，但setUpWebViewController是异步的，build方法会在initState结束后立刻执行，此时_controller可能还没被赋值，自然会报错。

这里给你几个可行的解决思路：

用FutureBuilder等待初始化完成
把WebView的构建放在FutureBuilder里，等待_initialization完成后再渲染，确保_controller已经初始化：

@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: _initialization,
    builder: (context, snapshot) {
      if (snapshot.connectionState == ConnectionState.done) {
        // 初始化完成，渲染WebView
        return WebViewWidget(controller: _controller);
      } else {
        // 初始化中，显示加载状态
        return const Center(child: CircularProgressIndicator());
      }
    },
  );
}

检查是否有提前访问_controller的代码
看看你的setNavigation()方法，里面直接调用了_controller.setNavigationDelegate，虽然_controller已经被赋值，但要确保后续配置逻辑不会依赖未完成的异步操作。另外注意setUpWebViewController里重复实例化了mqttService，可以优化避免重复创建。
考虑使用Nullable类型替代late
如果你不想用late，可以把_controller声明为WebViewController?，然后在使用时做非空判断，不过这种方式需要处理更多空安全逻辑：
```
WebViewController? _controller;

// 在build里
if (_controller != null) {
  return WebViewWidget(controller: _controller!);
} else {
  return const Center(child: CircularProgressIndicator());
}
```

希望这些思路能帮你解决问题，如果还有其他细节可以补充，大家一起讨论！

内容来源于stack exchange

Flutter中WebViewController的延迟初始化错误排查求助

可能的解决方案： #

可能的解决方案：