Flutter Web使用GoRouter时浏览器返回按钮失效问题排查

点击自定义导航项时路由跳转正常，但点击浏览器返回按钮时，地址栏URL正确变更，但页面内容不更新（现象：地址栏切换到历史路径，页面仍停留在当前页面无变化）。

现有代码片段 #

路由配置（routes.dart） #

final key = GlobalKey<NavigatorState>();

final routerProvider = Provider<GoRouter>((ref) {
  final authState = ref.watch(authStateProvider);

  return GoRouter(
    navigatorKey: key,
    debugLogDiagnostics: true,
    initialLocation: PreLoginHome.routeLocation,
    routes: [
      GoRoute(
        path: SplashPage.routeLocation,
        name: SplashPage.routeName,
        builder: (context, state) {
          return const SplashPage();
        },
      ),
      GoRoute(
        path: PreLoginHome.routeLocation,
        name: PreLoginHome.routeName,
        builder: (context, state) {
          return const PreLoginHome();
        },
      ),
      // 其他路由省略
    ],
  );
});

主应用入口 #

class MyAppWithFirebase extends ConsumerWidget {
  const MyAppWithFirebase({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final router = ref.watch(routerProvider);
    return MaterialApp.router(
      theme: CustomTheme.darkTheme,
      routeInformationParser: router.routeInformationParser,
      routerDelegate: router.routerDelegate,
      routeInformationProvider: router.routeInformationProvider,
    );
  }
}

自定义导航按钮实现 #

Padding(
  padding: const EdgeInsets.fromLTRB(0, 0, 25, 0),
  child: TextButton(
      onPressed: isUserSignedIn
          ? () => ref.read(routerProvider).go(Dashboard.routeLocation)
          : () => ref.read(routerProvider).go(PreLoginHome.routeLocation),
      child: isUserSignedIn
          ? const Text('Dashboard')
          : const Text('Home')),
),
Padding(
  padding: const EdgeInsets.fromLTRB(0, 0, 25, 0),
  child: isUserSignedIn
      ? const ProblemsDropDownButton()
      : TextButton(
          onPressed: isUserSignedIn
              ? () => ref.read(routerProvider).go('/flashcard_solve')
              : (() => ref.read(routerProvider).go('/about')),
          child: isUserSignedIn
              ? const Text('Problems')
              : const Text('About')),
),

问题原因与解决方法 #

核心原因 #

问题出在全局定义的GlobalKey<NavigatorState>：这个全局key会导致GoRouter无法正确关联浏览器历史变化后的路由状态，进而无法触发页面重建。

修复步骤 #

1. 将NavigatorKey移至Provider内部
   不要把GlobalKey<NavigatorState>定义为全局变量，而是在Provider的回调函数内创建，确保每次路由状态更新时能正确绑定：

   final routerProvider = Provider<GoRouter>((ref) {
     final authState = ref.watch(authStateProvider);
     // 在Provider内部创建导航key，避免全局引用导致的状态失效
     final navigatorKey = GlobalKey<NavigatorState>();
   
     return GoRouter(
       navigatorKey: navigatorKey,
       debugLogDiagnostics: true,
       initialLocation: PreLoginHome.routeLocation,
       routes: [
         // 你的路由配置
       ],
     );
   });
   

2. 添加状态监听（可选）
   如果路由依赖authState这类动态状态，需要让GoRouter监听状态变化，确保路由能响应状态更新：

   final routerProvider = Provider<GoRouter>((ref) {
     final authState = ref.watch(authStateProvider);
     final navigatorKey = GlobalKey<NavigatorState>();
   
     return GoRouter(
       navigatorKey: navigatorKey,
       debugLogDiagnostics: true,
       initialLocation: PreLoginHome.routeLocation,
       // 监听authState变化，自动刷新路由
       refreshListenable: GoRouterRefreshStream(authState),
       routes: [
         // 你的路由配置
       ],
     );
   });
   

   如果authState是ChangeNotifier类型，改用GoRouterRefreshNotifier即可。

3. 关于WillPopScope的说明
   在每个页面添加WillPopScope是可行的，但并非解决当前问题的必要方案——当前问题的根源是全局导航key导致的状态关联失效，修复key的定义即可解决，无需额外添加WillPopScope。

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