MaterialApp添加builder后GlobalKey导航失效的解决方法

问题根源 #

你在MaterialApp的builder回调里直接返回了HomePage()，这相当于把MaterialApp内部原本带Navigator的导航树给完全替换掉了。实际上builder的第二个参数child，就是MaterialApp根据home、routes配置生成的、绑定了navigatorKey的Navigator组件树。你忽略这个child，导致GlobalKey对应的Navigator根本没被渲染，自然没法触发导航。

解决办法 #

在builder的返回值里必须保留并使用传入的child参数，把它作为你自定义布局的子节点，这样原本的Navigator结构才能保留，GlobalKey也能正常绑定到它上面。

如果你的builder是用来加全局UI包裹（比如SafeArea、全局悬浮按钮），只需要把child嵌入进去就行，别直接返回HomePage。

修改后的完整代码 #

GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navigatorKey,
      home: HomePage(),
      theme: ThemeData(
        primaryColor: Color(0xffff5e57),
        colorScheme: ColorScheme.light(secondary: Color(0xffff3f34)),
      ),
      routes: {
        '/second_page': (context) => SecondPage(),
      },
      // 正确使用builder：保留child参数，它包含了绑定好的Navigator
      builder: (BuildContext context, Widget? child) {
        // 这里可以添加你的全局自定义UI，比如SafeArea、全局状态容器等
        return SafeArea(
          child: child!,
        );
        // 如果不需要额外包裹，直接返回child也可以：
        // return child;
      },
    );
  }
}

class SecondPage extends StatelessWidget {
  const SecondPage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Example'),
      ),
      body: Container(
        width: double.infinity,
        height: double.infinity,
        padding: EdgeInsets.all(16),
        child: Center(
          child: ElevatedButton(
            child: Text("Open New Page"),
            onPressed: _openNewPage,
          ),
        ),
      ),
    );
  }

  void _openNewPage() {
    navigatorKey.currentState?.pushNamed('/second_page');
  }
}

核心要点 #

• 永远不要在builder里直接替换掉child，它是MaterialApp内部导航结构的核心载体，navigatorKey绑定的就是这个结构里的Navigator。
• 如果需要通过builder实现全局UI效果，只需要把child嵌入到你的自定义组件中，保证导航树的完整性。

内容的提问来源于stack exchange，提问作者R Rifa Fauzi Komara