Flutter使用BottomNavigationBar出现!keyReservation.contains(key)错误如何解决

你遇到的报错核心是Flutter widget树中存在重复的全局Key（GlobalKey），触发报错的断言内容如下：

Failed assertion: line 3634 pos 18: '!keyReservation.contains(key)': is not true.

给子页面Scaffold添加Key后依然报错，通常由两个原因触发：

• 你提前将三个页面实例初始化后存储在pages列表中长期持有，若子页面内部使用了GlobalKey，切换页面时旧的widget实例未完全销毁就被复用，导致Key重复注册到框架的Key预留表中
• 多个子页面的组件绑定了同一个GlobalKey，包括子页面Scaffold设置的Key重复、或子页面内部自定义组件复用了同一个GlobalKey

方案1：动态构建页面（无保活需求优先选） #

取消提前实例化所有页面的逻辑，改为根据选中索引动态构建页面，避免长期持有页面实例导致的Key冲突，修改后代码如下：

class Home extends StatefulWidget {
  @override
  _HomeState createState() => _HomeState();
}

// 补全State的泛型绑定，消除隐式隐患
class _HomeState extends State<Home> {
  int _selectedIndex = 1;

  // 参数指定为int类型，不要用dynamic
  _onItemTapped(int index) {
    setState(() {
      _selectedIndex = index;
    });
  }

  // 按需返回对应页面实例，不提前缓存
  Widget _getCurrentPage() {
    switch(_selectedIndex) {
      case 0: return const MyOrders();
      case 1: return const HomeScreen();
      case 2: return const CartItems();
      default: return const HomeScreen();
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.white,
      bottomNavigationBar: BottomNavigationBar(
        items: const [
          BottomNavigationBarItem(
            icon: Icon(Icons.monetization_on_outlined),
            label: 'My Orders',
          ),
          BottomNavigationBarItem(
            icon: Icon(Icons.account_circle_outlined),
            label: 'Home',
          ),
          BottomNavigationBarItem(
            icon: Icon(Icons.work_outline),
            label: 'My Cart',
          ),
        ],
        currentIndex: _selectedIndex,  
        selectedItemColor: const Color(0xff232869),
        onTap: _onItemTapped,
      ),
      body: _getCurrentPage(),
    );
  }
}

方案2：IndexedStack保活（需要保留页面状态优先选） #

如果需要保留各页面的滚动位置、输入状态等，改用IndexedStack包裹所有页面，同时给每个子页面设置唯一的Key，配合子页面保活逻辑：

class _HomeState extends State<Home> {
  late List<Widget> pages;
  int _selectedIndex = 1;

  @override
  void initState() {
    super.initState();
    // 初始化时给每个页面分配唯一Key，避免Key冲突
    pages = [
      MyOrders(key: UniqueKey()),
      HomeScreen(key: UniqueKey()),
      CartItems(key: UniqueKey()),
    ];
  }

  _onItemTapped(int index) {
    setState(() {
      _selectedIndex = index;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.white,
      bottomNavigationBar: BottomNavigationBar(
        items: const [
          BottomNavigationBarItem(
            icon: Icon(Icons.monetization_on_outlined),
            label: 'My Orders',
          ),
          BottomNavigationBarItem(
            icon: Icon(Icons.account_circle_outlined),
            label: 'Home',
          ),
          BottomNavigationBarItem(
            icon: Icon(Icons.work_outline),
            label: 'My Cart',
          ),
        ],
        currentIndex: _selectedIndex,  
        selectedItemColor: const Color(0xff232869),
        onTap: _onItemTapped,
      ),
      // IndexedStack会同时保留所有页面的状态
      body: IndexedStack(
        index: _selectedIndex,
        children: pages,
      ),
    );
  }
}

同时需要给每个子页面（MyOrders、HomeScreen、CartItems）的State混入AutomaticKeepAliveClientMixin开启保活，示例如下：

class _HomeScreenState extends State<HomeScreen> with AutomaticKeepAliveClientMixin {
  // 开启页面保活
  @override
  bool get wantKeepAlive => true;

  @override
  Widget build(BuildContext context) {
    super.build(context); // 必须调用父类build方法
    // 原有页面逻辑
  }
}

方案3：全局排查GlobalKey使用 #

如果上述两个方案仍未解决问题，逐一检查三个子页面的代码，确保每个GlobalKey仅绑定到一个widget上，不要全局定义公用的GlobalKey给多个组件复用。

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