go_router与flutter_riverpod异常致页面空白及GlobalKey重复错误

问题场景 #

使用GoRouter做路由、Flutter Riverpod做状态管理的Flutter应用，包含Login、Home、Settings三个页面，其中Home和Settings通过底部导航栏切换。点击Settings页面的「抛出异常的登出」按钮后，应用出现空白页面，控制台抛出Duplicate GlobalKey detected in widget tree错误，预期是不执行登出、保持当前页面无变化。

核心原因 #

这个异常的本质是Widget树中存在重复的GlobalKey实例，通常由以下情况导致：

• 登出逻辑触发时，旧页面（底部导航栏所在页面）还未完全销毁，新路由（如Login页）就已挂载，导致底部导航栏相关组件的GlobalKey被重复绑定
• 状态更新与路由跳转的时序混乱，Riverpod状态变更触发Widget重建时，GoRouter的路由切换操作同时修改Widget树，引发Key冲突

解决方案 #

1. 严格控制登出逻辑的触发条件 #

如果预期是不执行登出，直接在按钮点击事件中添加判断，阻止不必要的状态更新或路由跳转：

// Settings页面的登出按钮
ElevatedButton(
  onPressed: () {
    // 添加业务判断，只有满足条件才执行登出，否则直接返回
    bool shouldLogout = false; // 替换为你的实际判断逻辑
    if (!shouldLogout) return;
    
    // 若允许登出，再执行后续逻辑（如状态更新）
    // ref.read(logoutProvider.notifier).state = true;
  },
  child: const Text('抛出异常的登出'),
)

2. 修复GlobalKey的使用方式 #

检查底部导航栏相关组件（如TabBarView、嵌套Navigator）的GlobalKey是否为全局静态实例，改为在StatefulWidget的State中初始化，确保每个Widget实例拥有唯一的Key：

class BottomNavShell extends StatefulWidget {
  const BottomNavShell({super.key, required this.child});
  final Widget child;

  @override
  State<BottomNavShell> createState() => _BottomNavShellState();
}

class _BottomNavShellState extends State<BottomNavShell> {
  // 在State内部初始化GlobalKey，每个实例拥有独立的Key
  final _navigatorKey = GlobalKey<NavigatorState>();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Navigator(
        key: _navigatorKey,
        onGenerateRoute: (settings) => MaterialPageRoute(
          builder: (context) => widget.child,
        ),
      ),
      bottomNavigationBar: BottomNavigationBar(
        // ... 导航项配置
      ),
    );
  }
}

3. 调整路由与状态更新的时序 #

如果需要执行登出操作，避免同步触发状态更新和路由跳转，改用Riverpod的ref.listen监听状态变化，确保Widget树完成更新后再执行路由操作：

// 定义登出状态Provider
final logoutStateProvider = StateProvider<bool>((ref) => false);

// 在Settings页面中监听状态
@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    ref.listen(logoutStateProvider, (previous, next) {
      if (next) {
        // 先重置状态，再执行路由跳转
        ref.read(logoutStateProvider.notifier).state = false;
        // 使用replace替换当前路由，避免栈中残留旧页面引发冲突
        GoRouter.of(context).replace('/login');
      }
    });
  });
}

4. 使用ShellRoute优化底部导航路由结构 #

用GoRouter的ShellRoute包裹底部导航相关页面，确保切换页面时不会重建整个导航壳，减少Widget树重建带来的Key冲突：

final appRouter = GoRouter(
  initialLocation: '/login',
  routes: [
    GoRoute(
      path: '/login',
      builder: (context, state) => const LoginPage(),
    ),
    ShellRoute(
      builder: (context, state, child) => BottomNavShell(child: child),
      routes: [
        GoRoute(
          path: '/home',
          builder: (context, state) => const HomePage(),
        ),
        GoRoute(
          path: '/settings',
          builder: (context, state) => const SettingsPage(),
        ),
      ],
    ),
  ],
);

5. 添加错误兜底避免空白页面 #

在MaterialApp.router中配置错误Widget，即使出现异常也不会显示空白页面：

MaterialApp.router(
  routerConfig: appRouter,
  builder: (context, child) {
    ErrorWidget.builder = (FlutterErrorDetails details) {
      return Scaffold(
        body: Center(
          child: Text('页面出错：${details.exception.toString()}'),
        ),
      );
    };
    return child!;
  },
);

内容的提问来源于stack exchange，提问作者Zia Ur Rahman