问题现象

在 Flutter 以 Fragment 方式嵌入到原生 Android 的混合项目中，全面屏设备侧滑返回或点击系统返回键时，应用直接退出（Activity onDestroy），而非预期行为：

• 子页面：应返回上一页
• 首页：应提示「再按一次退出」，第二次才真正退出

根本原因

FlutterFragment 默认未启用 shouldAutomaticallyHandleOnBackPressed，导致返回事件未传递给 Flutter。

事件链路实际为：

1. 用户触发返回（物理键 / 手势）
2. Android 系统将 KEYCODE_BACK 发给 Activity
3. 由于 FlutterFragment 未注册 OnBackPressedCallback，系统直接执行默认行为
4. Activity 被 finish，应用退出
5. Flutter 层完全收不到返回事件，PopScope、NavigatorObserver 等都不会被触发

解决思路

1. Android 侧：启用 FlutterFragment 的自动返回处理

在创建 FlutterFragment 时，显式开启 shouldAutomaticallyHandleOnBackPressed(true)：

flutterFragment = FlutterFragment.withCachedEngine(FLUTTER_ENGINE_ID)
    .shouldAttachEngineToActivity(true)
    .shouldAutomaticallyHandleOnBackPressed(true)  // 关键：将返回事件交给 Flutter 处理
    .build();

开启后：

1. FlutterFragment 向 Activity 的 OnBackPressedDispatcher 注册回调
2. 返回键/手势到达时，先由该回调处理
3. 回调内部调用 navigationChannel.popRoute()，把事件交给 Flutter 导航栈
4. Flutter 的 PopScope、 Navigator 等才能正常介入

2. Flutter 侧：路由转场与首页拦截

• 子页面：使用 Transition.cupertino，让侧滑手势由 Flutter 的 Cupertino 转场接管，行为与系统一致
• 首页：用 PopScope 配合 canPop: false 拦截返回，实现「再按一次退出」

// 首页
PopScope(
  canPop: false,
  onPopInvokedWithResult: (didPop, result) async {
    if (didPop) return;
    if (!mounted) return;
    final nav = Navigator.of(context);
    if (nav.canPop()) {
      nav.pop();  // 理论上不应出现
      return;
    }
    // 首页：第一次提示，第二次退出
    if (_lastBackAt != null && DateTime.now().difference(_lastBackAt!).inSeconds < 2) {
      SystemNavigator.pop();
      return;
    }
    _lastBackAt = DateTime.now();
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('再按一次退出应用')),
    );
  },
  child: Scaffold(...),
)

排查过程简述

1. 加日志确认是否进入 Flutter
   在 PopScope、NavigatorObserver 等处打 [BackDebug] 日志，发现按返回时没有任何 Flutter 日志，但 Activity 立刻 onDestroy，说明事件没到 Flutter。
2. 查 Android 层
   Activity 未重写 onBackPressed，说明是默认行为。问题在 Fragment 与 Activity 的返回事件分发上。
3. 查 FlutterFragment 文档
   发现 ARG_SHOULD_AUTOMATICALLY_HANDLE_ON_BACK_PRESSED 默认为 false，需要显式设为 true。

经验总结

参考资料

• FlutterFragment 官方文档
• FlutterFragment.CachedEngineFragmentBuilder - shouldAutomaticallyHandleOnBackPressed
• Add a Flutter Fragment to an Android app