Flutter跳转路由时报Navigator.onGenerateRoute为null错误如何解决

错误提示Navigator.onGenerateRoute was null, but the route named "/all-category-screen" was referenced.的核心原因是导航器没有找到绑定的路由生成回调，你可以按以下顺序排查： #

1. 检查MaterialApp的基础路由配置 #

90%以上的该类错误都是漏了将自定义的AppRouter.onGenerateRoute绑定到MaterialApp的对应参数，正确配置示例：

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // 必须添加该行，将你编写的路由生成逻辑绑定到导航器
      onGenerateRoute: AppRouter.onGenerateRoute,
      // 初始路由如果配置了，要保证对应名称在AppRouter的switch分支中存在
      initialRoute: WelcomeScreen.routeName,
      // 注意：不要同时配置routes参数和onGenerateRoute，二者选其一即可避免冲突
    );
  }
}

额外注意：如果项目中存在多层嵌套的MaterialApp（比如全局壳子、独立模块单独配置的MaterialApp），必须保证触发跳转的context所属的Navigator对应的MaterialApp已经配置了onGenerateRoute，否则调用内层context跳转也会触发该错误。

2. 检查BLoC认证逻辑的路由配置 #

如果你是通过BLoC状态判断切换不同的页面入口，需要确认所有分支返回的MaterialApp都统一配置了onGenerateRoute，避免出现部分分支漏配的情况：

错误示例： #

BlocBuilder<AuthBloc, AuthState>(
  builder: (context, state) {
    if (state is AuthAuthenticated) {
      // 已认证状态返回的MaterialApp漏配了onGenerateRoute
      return MaterialApp(home: const MainScreen());
    } else {
      return MaterialApp(
        home: const WelcomeScreen(),
        onGenerateRoute: AppRouter.onGenerateRoute,
      );
    }
  }
)

修正方案： #

将MaterialApp提至BLoC builder外层，路由守卫逻辑放到onGenerateRoute中实现，或者给所有分支的MaterialApp都统一配置onGenerateRoute参数。 #

3. 辅助验证排查 #

如果以上配置都确认无误，可以用直接构建路由的方式跳转验证：

Navigator.of(context).push(MaterialPageRoute(builder: (_) => const AllCategoryScreen()));

如果可以正常跳转，说明路由生成逻辑本身没有问题，还是onGenerateRoute绑定环节存在疏漏。
同时可以打印AllCategoryScreen.routeName的值，确认和报错的路由名称"/all-category-screen"完全一致，大小写、前缀斜杠都没有差异。

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