Flutter2升级后pushReplacement、pushAndRemoveUntil失效仅Navigator.push可用

问题产生根源 #

Flutter 2 正式将Navigator 2.0 声明式路由体系纳入核心框架后，对路由栈管理逻辑做了明确的边界拆分：

• 所有与Page对象绑定的路由（即报错中提及的page-based route），完全由声明式的pages列表驱动状态更新，这类路由会被框架标记hasPage = true属性
• 框架明确禁止通过命令式路由API（如pushReplacement、pushAndRemoveUntil这类接收Route对象为入参的方法）直接操作这类带Page绑定的路由，因为命令式操作不会同步更新Navigator内部维护的pages列表状态，容易造成路由栈与组件渲染状态不一致，因此加入了强制断言拦截
• 触发当前报错的直接原因：调用pushAndRemoveUntil时，设置的路由移除谓词返回false（即要求清空栈内所有路由），而栈内包含了由初始home或声明式pages生成的、带Page绑定的路由，此时通过命令式API移除这类路由，就会触发断言校验失败
• 仅Navigator.push可正常使用的原因：push操作只是往栈顶新增独立的、无Page绑定的自定义路由，不会修改栈内已存在的带Page绑定的路由状态，因此不会触发拦截逻辑。

对应解决方法 #

根据项目的路由使用场景，可选择对应方案落地：

场景1：项目仍使用传统命令式路由，未接入声明式路由体系/第三方声明式路由框架 #

这类场景的核心调整是：涉及清空路由栈、替换栈内路由的操作，不再依赖命令式API遍历移除路由，直接通过修改Navigator的pages列表完成栈状态更新，从根源上避免触发page-based路由的操作拦截。

以示例中“跳转登录页并清空全栈”的需求为例，原写法会触发断言，可替换为如下实现：

// 先移除栈内所有原有路由
Navigator.of(context).popUntil((route) => false);
// 直接更新Navigator的pages列表，加入登录页对应的Page对象
Navigator.of(context).pages = [
  MaterialPage(
    child: LoginScreen(),
    // 保留原有自定义转场配置
    transitionDuration: const Duration(milliseconds: 3300),
    transitionsBuilder: (context, animation, secondaryAnimation, child) {
      return _CustomPageTransition(
        routeAnimation: animation,
        fullscreenDialog: false,
        child: child
      );
    },
  )
];

注意：默认构造的MaterialApp会自动将初始home页对应的路由标记为带Page绑定的路由，这类路由无法通过命令式API直接移除，必须通过pages列表的方式更新状态。

场景2：项目已接入声明式路由框架（如官方MaterialApp.router、第三方go_router、auto_route等） #

这类场景需要完全替换原生Navigator的命令式栈操作API，改用路由框架提供的栈管理方法：

• 例如使用go_router实现清空全栈跳登录页的逻辑时，直接调用context.go('/login')即可，框架会自动维护pages列表的状态同步，不会触发底层断言
• 禁止在声明式路由驱动的应用中，直接调用Navigator.pushAndRemoveUntil、pushReplacement这类原生命令式方法修改路由栈结构

临时兼容方案（不推荐长期使用） #

如果临时无法完成路由逻辑迁移，可在创建自定义PageRouteBuilder时，手动覆盖路由的hasPage属性为false，绕过断言校验。但这种方式会带来路由栈状态不同步的潜在风险，容易出现返回键逻辑失效、页面栈与实际展示不匹配的问题，不建议作为长期方案使用。

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