Flutter命名路由配置错误导致页面无法跳转报错修复

问题背景 #

• 开发小型Flutter应用时，普通路由跳转原本运行正常，改用命名路由实现多页面跳转后出现运行报错
• 预期效果：点击登录页的登录按钮，触发对应路由逻辑完成页面跳转

问题根因 #

• 路由表配置位置错误：命名路由表routes是顶层MaterialApp/CupertinoApp的专属属性，当前代码错误将路由表写在Scaffold组件上，Flutter无法识别到路由映射关系，调用Navigator.pushNamed时找不到对应路由就会抛出异常
• 代码存在冗余问题：HomePage中重复导入了routes.dart文件；类名loginPage不符合Dart大驼峰命名规范

问题相关原始代码 #

首页（HomePage）代码 #

import 'package:flutter/material.dart';
import 'package:flutter_practice/pages/loginPage.dart';
import 'package:flutter_practice/pages/routes.dart';
import 'package:flutter_practice/pages/routes.dart';

class HomePage extends StatelessWidget {
  final int a = 30;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Catalog App"),
      ),
      body: Center(
        child: Container(
          child: Text("Welcome to flutter bhai $a"),
        ),
      ),
      drawer: Drawer(),
      routes: {
        MyRoutes.homeRoute: (context) => HomePage(),
        MyRoutes.loginRoute: (context) => loginPage(),
      },
    );
  }
}

登录页（loginPage）代码 #

import 'package:flutter/material.dart';
import 'package:flutter_practice/pages/routes.dart';

class loginPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Material(
        color: Colors.white,
        child: Column(
          children: [
            Image.asset(
              "assets/images/login_image.png",
              fit: BoxFit.cover,
            ),
            Text(
              "Login",
              style: TextStyle(
                fontSize: 24,
                fontWeight: FontWeight.bold,
              ),
            ),
            SizedBox(
              height: 20,
              child: Text("Hi, I am in the box"),
            ),
            Padding(
              padding:
                  const EdgeInsets.symmetric(vertical: 16.0, horizontal: 32.0),
              child: Column(
                children: [
                  TextFormField(
                    decoration: InputDecoration(
                      hintText: "Enter User Name",
                      labelText: "User Name",
                    ),
                  ),
                  TextFormField(
                    obscureText: true,
                    decoration: InputDecoration(
                      hintText: "Enter Password",
                      labelText: "Password",
                    ),
                  ),
                ],
              ),
            ),
            SizedBox(
              height: 20,
            ),
            ElevatedButton(
                onPressed: () {
                  Navigator.pushNamed(context, MyRoutes.homeRoute); 
                },
                child: Text("login"),
                style: TextButton.styleFrom()),
          ],
        ));
  }
}

路由常量配置文件代码 #

class MyRoutes {
  static String loginRoute = "/login";
  static String homeRoute = "/home";
}

修复方案 #

1. 清理HomePage中的错误配置：删除Scaffold上无效的routes属性，删除重复的routes.dart导入语句
2. 在应用入口（通常为main.dart）的顶层MaterialApp组件上配置路由表，同时指定初始路由，参考代码如下：

import 'package:flutter/material.dart';
import 'package:flutter_practice/pages/homePage.dart';
import 'package:flutter_practice/pages/loginPage.dart';
import 'package:flutter_practice/pages/routes.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      // 配置应用初始加载的路由
      initialRoute: MyRoutes.homeRoute,
      // 命名路由表必须配置在MaterialApp的routes属性下
      routes: {
        MyRoutes.homeRoute: (context) => const HomePage(),
        MyRoutes.loginRoute: (context) => const loginPage(),
      },
    );
  }
}

3. （规范优化）将登录页类名loginPage修改为大驼峰格式LoginPage，同步修改所有引用该类的位置，符合Dart官方开发规范

注意：所有通过Navigator.pushNamed跳转的路由名，必须在MaterialApp的routes表中存在对应映射，否则依然会抛出找不到路由的错误。

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