最近把一个用 startActivity 堆起来的项目改成单 Activity 架构时我把 Navigation 导航图重新完整用了一遍边做边整理这些笔记。标题里写了“测试通过”不是随便说说——我在 API 21、API 29、API 34 三台设备上手跑过完整流程连续跳转、参数传递、返回栈清理、深链唤起都验证了一遍确认这套方案在常规业务场景下稳定可用才决定把过程写出来。Navigation 是 Android 官方推荐的导航框架核心思路是把页面跳转、参数传递、返回栈管理、深链配置统一成一份导航图。导航图本质上是一份 XML 文件你把所有页面destination和跳转关系action都画在里面剩下的交给框架处理。传统写法里FragmentTransaction 提交、Bundle 传参、addToBackStack 手动维护这些样板代码在 Navigation 里基本不需要自己写了。哪怕你之前完全没接触过导航图只要用过 Fragment花半天时间看完这份分享基本就能在自己的项目里把最核心的跳转链路搭起来。这次分享会覆盖设计思路、环境配置、三种典型跳转写法、返回栈清理策略、实战中容易踩的坑以及一套可复用的验证清单。我尽量把选择和取舍背后的原因也讲清楚不光是贴代码。1. 为什么 Navigation 能简化设计1.1 传统跳转方式的问题在哪写 Android 的人对这套代码不会陌生先findFragmentById或者newInstance然后FragmentTransaction再addToBackStack如果页面要传参还得定义一堆KEY_xxx常量。页面少的时候还好一旦超过十几个麻烦就集中在几个地方。第一样板代码重复度高。每个跳转都要写 FragmentTransaction、写 add还要处理 Fragment 的 attach、detach 各种生命周期代码量一大读起来全是噪音。第二返回栈完全靠手动管理。你想从 A 跳到 C 之后不让用户按返回回到 B就得自己popBackStack稍有遗漏返回逻辑就和预期不一致。第三参数传递出错率很高。key 拼错、类型写错编译时不报错运行到跳转那一行才崩排查成本不低。第四深链配置分散。你需要在 Manifest 里为每个页面重复声明 intent-filter同一份深链逻辑要被维护两次。这几个问题在小项目里显得不致命但一旦页面数量上来了每次新增页面都要在所有涉及跳转的地方做调整很容易改一处崩三处。1.2 Navigation 的三个核心角色Navigation 把这套流程抽象成三个角色导航图Navigation Graph、NavHostFragment、NavController。导航图是页面跳转关系的地图定义哪些页面可以互相跳转NavHostFragment 是地图展示的容器负责承载 Fragment 的切换NavController 是执行导航动作的控制器负责把动作应用到容器中。你可以把 Navigation 理解成一套车载导航导航图是地图标注了所有可达地点和路线NavHostFragment 是车内那块显示屏幕负责展示当前所在位置NavController 就是开车的人听从你的指令在地图上规划路线并执行。我们平时做跳转其实只需要告诉 NavController“我要去哪个目的地”它会自己处理 Fragment 的创建、销毁和返回栈维护。Fragment 页面之间的跳转以前普遍是自己写管理类把每个 Fragment 的实例、tag、栈状态都集中在一个类里。Navigation 接管这件事之后你不再需要在业务代码里关心 Fragment 到底 add 还是 replace、返回栈里当前栈顶是谁——这些都被导航图封装好了。1.3 简化设计的具体收益我用实际项目对比过页面从 8 个增加到 20 个时旧实现里的跳转相关代码体量和新增页面成本都是直线上升而且每次修改都可能引入新的返回栈问题。切换 Navigation 之后新增页面只需要三步在导航图里加一个 destination、加一条 action、在按钮回调里调用一次 navigate。参数传递改用 Safe Args 之后key 和 type 都有编译期校验不再靠人肉记忆字符串。还有一点很关键Navigation 官方扩展NavigationUI做了底部导航栏、抽屉栏的联动适配配合BottomNavigationView时选中态、返回栈、标题栏都在一个地方统一维护不用再写 TabSelectedListener 来回切 Fragment。单 Activity Navigation 现在基本是官方推荐的主架构对新手来说学习成本也比自己造一套 Fragment 管理框架低很多。2. 环境准备与导航图创建2.1 依赖配置与版本选择我用的是当前 stable 分支的 2.7.7 版本。这个系列从 2.4 开始稳定性已经足够好API 变更也收敛了老项目升级比较稳妥。在模块的 build.gradle 里加上dependencies { implementation androidx.navigation:navigation-fragment-ktx:2.7.7 implementation androidx.navigation:navigation-ui-ktx:2.7.7 }如果要使用 Safe Args 类型安全传参需要在项目根 build.gradle 声明插件buildscript { dependencies { classpath androidx.navigation:navigation-safe-args-gradle-plugin:2.7.7 } }然后在模块 build.gradle 顶部应用plugins { id androidx.navigation.safeargs }如果项目是纯 Java 写的可以应用safeargs插件如果是 Kotlin用safeargs.kotlin更合适。需要注意的是Safe Args 插件生成的代码目录是 build/generated/source/navigation-args如果 IDE 识别不到生成的 Directions 类刷新 Gradle 或者重新 build 一般就能解决。2.2 创建导航图文件在 res 目录下新建navigation文件夹然后创建nav_graph.xml。一个最基础的导航图长这样navigation xmlns:androidhttp://schemas.android.com/apk/res/android xmlns:apphttp://schemas.android.com/apk/res-auto android:idid/nav_graph app:startDestinationid/homeFragment fragment android:idid/homeFragment android:namecom.example.app.ui.home.HomeFragment android:label首页 action android:idid/action_homeFragment_to_detailFragment app:destinationid/detailFragment / /fragment fragment android:idid/detailFragment android:namecom.example.app.ui.detail.DetailFragment android:label详情 / /navigationapp:startDestination是 App 启动后默认展示的页面这里指向 homeFragment。每个 destination 的android:id是全局唯一的跳转时会用这个 id 定位目标页面。android:name必须是 Fragment 的完整限定类名如果配置成不带包名的简单类名启动时反射会失败直接闪退。action 是跳转关系的定义一个 action 可以理解为一条有名字的路线。点击事件里调用navigate(R.id.action_homeFragment_to_detailFragment)框架就会沿着这条路线从 homeFragment 走到 detailFragment同时把 homeFragment 加入返回栈。导航图在 Android Studio 里有可视化设计器拖拽就能建页面但实际调试问题时不看 XML 很难定位建议至少会读 XML 结构。2.3 让 Activity 承载导航图在 Activity 的布局文件里加一个 NavHostFragment 容器androidx.fragment.app.FragmentContainerView android:idid/nav_host_fragment android:nameandroidx.navigation.fragment.NavHostFragment android:layout_widthmatch_parent android:layout_heightmatch_parent app:defaultNavHosttrue app:navGraphnavigation/nav_graph /这里app:defaultNavHosttrue是关键它会确保系统返回键交给 NavController 处理而不是让 Activity 默认行为接管。app:navGraph指向刚才创建的导航图文件。在 Activity 的 onCreate 里通过 FragmentContainerView 获取 NavControllerval navHostFragment supportFragmentManager .findFragmentById(R.id.nav_host_fragment) as NavHostFragment val navController navHostFragment.navController之后所有页面跳转都通过这个 navController 进行Activity 本身不用再关心任何 Fragment 切换细节。如果你的 App 有多个入口页面也可以在代码里动态设置起始页navController.graph.startDestination R.id.xxxFragment这比写死在 XML 里更灵活。注意FragmentContainerView 的android:id和导航图 startDestination 对应的 Fragment 容器 id 不要共用同一个 id。如果你在布局里用了R.id.nav_host_fragment导航图里的页面 id 就不要重复给。两者作用域不同但混用容易让自己困惑排查时很难看出是哪一层配错了。3. 三种实际跳转场景的实现3.1 基础跳转从列表页进详情页最常见的场景是列表页点一项跳转详情页并带上数据。在导航图里先定义好 action然后在点击事件里调用view.findViewByIdButton(R.id.btn_detail).setOnClickListener { it.findNavController().navigate(R.id.action_homeFragment_to_detailFragment) }findNavController()可以从任意 View 向上寻找 NavController所以在 Fragment 的 onCreateView 里直接拿 view 调用即可。navigate 方法的参数里还可以传一个 Bundle这是原生传参方式val bundle bundleOf(itemId to itemId, title to itemTitle) findNavController().navigate(R.id.action_homeFragment_to_detailFragment, bundle)接收方在getArguments()里按 key 取数据。这种方式简单直接但 key 和类型依然靠人肉保证一致一旦 key 拼错运行期拿到 null最坑的是不一定崩溃只是页面展示异常排查成本很高。3.2 推荐方式Safe Args 类型安全传参引入 Safe Args 插件后导航图里定义的带参数 Fragment 会生成对应 Direction 类和 Args 类。给 detailFragment 添加 argumentfragment android:idid/detailFragment android:namecom.example.app.ui.detail.DetailFragment argument android:nameitemId app:argTypestring android:defaultValue0 / argument android:nametitle app:argTypestring app:nullablefalse / /fragment然后跳转代码可以这样写val action HomeFragmentDirections.actionHomeFragmentToDetailFragment( itemId 12345, title 标题文字 ) findNavController().navigate(action)生成的 Directions 类会生成一个带全部参数的方法参数类型、顺序都由编译期保证key 根本不会拼错。接收方用DetailFragmentArgs.fromBundle(requireArguments())拿到的就是强类型对象val args DetailFragmentArgs.fromBundle(requireArguments()) textView.text args.title关于app:argType如果你传的是自定义 Parcelable 类型记得在 argType 里写全限定类名同时该类型必须实现 Parcelable 或 Serializable。项目里遇到过传 Parcelable 时直接闪退就是类名没写完整反射找不到。3.3 返回栈清理popUpTo 与 popUpToInclusive返回栈的清理是 Navigation 相比手动管理最值钱的能力。先看一个高频场景登录流程走“登录页 - 注册页 - 主页”注册完成后跳到主页返回时不应该再回到注册页和登录页。导航图配置可以这样action android:idid/action_registerFragment_to_mainFragment app:destinationid/mainFragment app:popUpToid/loginFragment app:popUpToInclusivetrue /这段配置的意思是从 registerFragment 跳到 mainFragment 时把返回栈里在 loginFragment 之上的页面包括 loginFragment 自己全部出栈。最终结果是从主页按返回键直接退出 App而不是回到登录页。popUpTo指定清理到哪一个 destinationpopUpToInclusive决定这个 destination 本身是否也被移除。如果只写app:popUpToid/loginFragment则 loginFragment 保留在栈里用户可以从主页按返回回到登录页。这两个配置组合起来非常灵活多步表单向导、支付流程跳转收银台这类场景都能用同一套机制处理。3.4 深链唤起与外部跳转Navigation 支持把 destination 配置为深链目标外部通过 URL 或 intent 直接唤起指定页面fragment android:idid/promotionFragment android:namecom.example.app.ui.promotion.PromotionFragment deepLink app:urihttps://example.com/promotion/{promotionId} / /fragment在 Manifest 里对应 Activity 声明 intent-filter 后外部链接就能直接打开 promotionFragment。注意大括号里的 promotionId 是占位符Navigation 会自动把它作为导航参数注入不用手动解析 query。用 adb 测试adb shell am start -W -a android.intent.action.VIEW -d https://example.com/promotion/9527 com.example.app深链同样可以使用popUpTo和popUpToInclusive在用户从外部链接进入页面后控制返回行为是否符合预期。这套机制做消息推送落地页、分享卡片打开页面尤其方便省掉了手动解析 intent 再跳转的一大段代码。4. 实战中躲不开的坑与排查方案4.1 页面加载一闪而过或直接闪退最常见的是导航图里某个 fragment 的android:name写错运行到该页面时抛ClassNotFoundException。这个错误在 Android Studio 里往往只显示一个InflateException定位不了是哪个页面的问题。解决办法很朴素先在导航图里把 startDestination 换成能加载的页面再逐个点击检查。逐页点击排查虽然原始但是效率比盯着日志猜高。第二个容易踩的是 Fragment 类的构造函数问题。Navigation 框架通过反射创建 Fragment要求有且仅有一个无参构造方法。如果 Fragment 里定义了带参构造来传数据千万别用于默认构造改用 Arguments 传递否则运行期直接崩。4.2 连续点击造成二次跳转用户手速快按钮连续点两次同一个导航动作触发两次页面就崩了。这不是 Navigation 独有startActivity 时代也有但 Navigation 下表现更明显因为 Fragment 在切换动画过程中如果再次执行 navigate很容易把状态搞乱。我的做法是在基类 Fragment 的点击事件里做防抖用一个布尔值标记是否正在导航第一次点击置为 true导航完成或页面销毁前不允许再次触发。private var navigationLocked false fun safeNavigate(actionId: Int) { if (navigationLocked) return navigationLocked true findNavController().navigate(actionId) view?.postDelayed({ navigationLocked false }, 500) }这类防抖代码放在基类里统一处理比每个页面单独维护优雅得多。另外app:launchSingleToptrue也能在一定程度上防止同一个 destination 在栈顶重复入栈但它解决不了跨页面连续点击问题防抖还是得写。4.3 未读消息角标、标题栏与返回键不同步NavigationUI 与 BottomNavigationView 联动时只要配置好setupWithNavController页面切换、标题变更、返回键都会自动维护。但有一种情况很容易翻车页面里用onBackPressedDispatcher自定义返回逻辑和 NavController 的返回处理同时生效导致返回行为不一致或者返回事件被吞掉。我的建议是自定义返回逻辑尽量放在 Fragment 的setOnBackPressedCallback里注册一个回调并在 onDestroyView 时移除。不要直接覆写 Activity 的 onBackPressed否则 Navigation 和业务逻辑会互相抢占控制权。在 Navigation 2.7 系列里系统返回键默认已经被 NavigationUI 接管额外加拦截逻辑时一定要先明白你的回调是追加到链路里还是顶替了原路径。4.4 状态恢复与进程被杀后的页面错乱Navigation 会帮 Fragment 保存返回栈状态Activity 被系统回收后重建时会自动恢复到之前的页面。这个机制绝大多数情况下好用但如果你在 Fragment 的onViewCreated里通过参数判断是否需要请求网络重建时参数还在数据重新加载是正常的。需要注意的问题是嵌套 Fragment 或内部持有大量 View 状态的自定义控件在状态恢复时可能抛出IllegalArgumentException或者 View 找不到。遇到这种情况不要在onViewCreated里堆积过多 UI 初始化把跟状态相关的字段放到onSaveInstanceState里或用 ViewModel 持有。Navigation 和 ViewModel 搭配最稳页面数据放 ViewModelActivity 重建时 ViewModel 还在推测状态恢复逻辑会更可控。4.5 系统版本适配差异Navigation 本身是兼容库不依赖具体系统版本差异但 Android 12 开始强制启用了 edge-to-edge 和新的返回手势后个别设备的系统栏会遮挡 Fragment 内容。这点不是 Navigation 的问题但会在实际使用中表现为“页面跳转后底部被手势条挡住一部分”或者“返回动画被系统手势干扰”。处理方法是在 Fragment 布局里正确设置View.setPadding或者用WindowInsetsCompat统一处理 insets。Navigation 自身只负责 Fragment 跳转不负责屏幕适配哪怕框架没换系统版本升级后也要专门过一轮视觉回归。Android 13、Android 14 继续强化了返回预测动画和 edge-to-edge如果你们项目适配范围到 Android 16建议在开发阶段就把这几项系统性检查纳入测试清单。4.6 fileprovider 和导航冲突的乌龙遇到过一种情况App 里同事引入了 fileprovider 用于文件分享同时 Navigation 的深链配置也有 intent-filter在测试深链时发现跳转偶尔不触发查半天发现是 Provider authorities 冲突导致 Manifest 合并失败。严格说这不是 Navigation 的锅但导航实现里往往会伴随着文件分享场景比如从相册选择图片后跳转裁剪页。这个阶段建议把 fileprovider 和所有 provider 的authorities都统一到一个常量类里管理不仅深链要测试安装包时 provider 冲突的问题也要在 CI 构建脚本里提前检查。除了 fileprovider涉及外部路径/storage/emulated/0/Android/data/...时还会遇到 scoped storage 的文件访问权限问题这些虽然不直接影响跳转但做多页面文件流转时容易和导航参数一起背锅。4.7 深链测试的正确姿势深链开发完后用浏览器直接打开链接测试经常不生效原因多半是 Manifest 里的 scheme/host 与深链 uri 不匹配或者浏览器跳转被系统拦截。更可靠的方式是先用 adb 命令测试 intent-filter 是否能直达adb shell am start -W -a android.intent.action.VIEW -d https://example.com/promotion/9527 com.example.app-W会等待启动完成如果 ACTION_VIEW 对应的 Activity 没找到logcat 里会有明确提示。注意深链 uri 里的占位符{promotionId}和 Navigation 的 argument 名称要完全一致否则深链能打开页面但参数是空的页面上所有数据都是空的这种问题很多时候要到业务层才发现。5. 测试验证与个人心得5.1 手动回归测试清单标题里写了“测试通过”说明至少要有一份可执行的验证清单。我一般按这个顺序过一遍冷启动直接启动 App进入 startDestination 对应页面无白屏、无闪退。连续跳转首页 - 列表 - 详情 - 详情下一层再逐层按返回键确认每一步返回的目标页和预期一致。参数传递详情页展示的数据与列表页点击项一致旋转屏幕后数据不丢失。深链从外部链接唤起对应页面返回行为符合 popUpTo 配置。任务栈从主页跳转 A 又跳转 B按返回键不应回到已经清理掉的页面。进程重建在开发者选项里开启“不保留活动”跳转几个页面后切后台再回前台恢复到预期页面且不出现叠影。底部导航联动切换底部 tab侧边栏选中态、页面标题同步更新。每一步我都在三个系统版本上跑。至少在 API 21 和 API 34 两个极端版本上验证过一次因为低版本上 Fragment 动画和生命周期行为差异最大。5.2 自动化验证方案手动验证覆盖场景有限我用 Espresso 做了一轮针对 Navigation 的自动化冒烟测试。思路很简单点击某个 View 后断言当前 Fragment 是否可见。Test fun navigateToDetail_showsDetailFragment() { onView(withId(R.id.btn_detail)).perform(click()) onView(withId(R.id.text_detail_title)) .check(matches(withText(标题文字))) }更细粒度一点可以直接获取 NavController 的 currentDestinationval navController activityRule .activity.supportFragmentManager .findFragmentById(R.id.nav_host_fragment) as NavHostFragment .navController assertEquals( R.id.detailFragment, navController.currentDestination?.id )这种断言能精确验证导航动作是否指向了正确目的地排除了页面有标题但跳错页面的情况。如果项目里已经有 UI 测试框架把核心导航链路固化成测试用例后续重构和升级就不会轻易弄坏跳转。5.3 从经验角度给的建议Navigation 把页面跳转的事收拢成了一个文件、一套 API它简化开发的效果是实实在在的。但框架帮你做了所有 Fragment 事务之后对 Fragment 生命周期和返回栈的理解不能省反而更重要。一旦遇到框架不预期的场景比如多个返回栈嵌套、对话框中的导航、自定义转场动画没有底层知识兜底问题会非常难排查。我实际遇到最耗时的坑是混用了旧代码里的FragmentManager.popBackStack()和 Navigation 返回链路导致返回栈状态和导航图描述不一致。最后统一把所有返回动作都改成 NavController 的操作问题自然消失。所以在项目里切 Navigation 时最理想的做法是把所有 Fragment 切换统一收口到 NavController不要留一部分用旧方式一部分用新方式。5.4 后续扩展空间Navigation 这套模型后续扩展方向很清晰深链作为运营入口给活动页、商品页都配上深链配合推送到达率统计很顺手多页面表单或引导流程可以用嵌套导航图管理步骤配合 ViewModel 做到 Fragment 状态在销毁重建时完整保留做一个文档编辑器或画板 App 时这种状态保留能让体验好很多。如果你们 App 正在往单 Activity 架构迁移Navigation 值得作为第一优先级的组件先落地它比迁移某个页面要影响面小得多但带来的代码结构改善却能辐射到所有页面。
