Flutter中GlobalKey被多组件占用：原因及解决方法

代码示例 #

final webViewKey = GlobalKey<WebViewContainerState>();
...
@override
Widget build(BuildContext context) {
  return Scaffold(
...
  body: FutureBuilder(
    future: getOptions(),
    builder: (BuildContext context, snapshot) {
      if (snapshot.hasData) {
        return Column(mainAxisAlignment: MainAxisAlignment.start, children: [
          Flexible(
            child: SizedBox(
              child: WebViewContainer(
                key: webViewKey,
              ),
            ),
          ),
        ]);
      } else {
        return const Text('');
      }
    },
  ),

触发的错误 #

The key [LabeledGlobalKey<WebViewContainerState>#0d5fc] was used by multiple widgets. The parents of those widgets were:
- WebViewContainer-[LabeledGlobalKey<WebViewContainerState>#0d5fc](state: WebViewContainerState#d188a)
- SizedBox(renderObject: RenderConstrainedBox#de300 relayoutBoundary=up2)
A GlobalKey can only be specified on one widget at a time in the widget tree.

问题原因 #

1. Future重复触发导致多次创建组件：你在build方法里直接调用getOptions()作为FutureBuilder的future参数，每次build执行时都会生成一个新的Future实例，导致FutureBuilder多次触发builder回调，反复创建WebViewContainer组件且都绑定同一个webViewKey。
2. 组件树更新的临时冲突：当Future状态变化时，旧的WebViewContainer可能还没被框架完全从组件树中卸载，新的实例就已经挂载，此时同一个GlobalKey被两个组件持有，触发异常。日志里的SizedBox是旧组件树中WebViewContainer的父节点，并非SizedBox本身使用了该key，只是用来标识冲突组件的位置。

解决办法 #

方法1：缓存Future，避免重复触发

把getOptions()的结果缓存到State中，只在初始化时执行一次，避免每次build生成新的Future：

late final Future _optionsFuture;

@override
void initState() {
  super.initState();
  _optionsFuture = getOptions(); // 仅初始化时执行
}

@override
Widget build(BuildContext context) {
  return Scaffold(
...
  body: FutureBuilder(
    future: _optionsFuture, // 使用缓存的Future
    builder: (BuildContext context, snapshot) {
      // 原有逻辑不变
    },
  ),
}

方法2：局部创建GlobalKey（适合无需保留状态的场景）

如果不需要在组件外部持有webViewKey，可以把GlobalKey的创建放到builder内部，确保每次创建WebViewContainer时使用独立的key：

builder: (BuildContext context, snapshot) {
  if (snapshot.hasData) {
    final webViewKey = GlobalKey<WebViewContainerState>(); // 局部创建key
    return Column(mainAxisAlignment: MainAxisAlignment.start, children: [
      Flexible(
        child: SizedBox(
          child: WebViewContainer(
            key: webViewKey,
          ),
        ),
      ),
    ]);
  } else {
    return const Text('');
  }
},

方法3：给父组件添加标识Key，帮助框架识别组件替换

通过给Column、Flexible添加Key，帮助框架准确识别组件的替换关系，减少旧组件残留的可能：

if (snapshot.hasData) {
  return Column(
    key: const ValueKey('web_view_column'),
    mainAxisAlignment: MainAxisAlignment.start,
    children: [
      Flexible(
        key: const ValueKey('web_view_flexible'),
        child: SizedBox(
          child: WebViewContainer(
            key: webViewKey,
          ),
        ),
      ),
    ],
  );
}

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