Compose Navigation Graph 是一个面向 Android Studio / IntelliJ IDEA 的 Jetpack Compose 导航可视化工具集。它通过 Gradle 插件、KSP 注解处理器、注解库和 IDE 插件，把应用中的 Compose 页面、路由参数、跳转关系和 @Preview 缩略图整合成一个可交互的导航流程图。它支持 Navigation 3、Navigation 2、其他 Compose 导航库，甚至普通 Activity；适合多模块 Android 项目用于理解、维护、评审和文档化应用导航结构。
适用领域
Android 开发 / Jetpack Compose / Kotlin / Kotlin Multiplatform / Compose Multiplatform / Android Studio 插件 / 导航架构可视化 / 代码静态分析 / UI Preview / 设计系统预览 / CI 导航变更校验 / 多模块工程治理
配置难度
中等。对于熟悉 Gradle、KSP、Jetpack Compose 和多模块 Android 项目的开发者，接入难度不高；但在大型老项目中，需要补充注解、处理 Preview 渲染问题、配置 variant 和 CI baseline，整体落地需要一定工程治理经验。
商业价值
较高。该项目可以显著提升 Android Compose 项目的可维护性和团队协作效率，尤其适合页面多、导航复杂、多模块拆分明显的业务 App。它能帮助新人快速理解应用结构，让代码评审关注导航变化，减少遗漏页面跳转的风险，并能生成可用于产品、设计和研发沟通的流程图与预览图库。对于中大型移动端团队，它的价值主要体现在降低认知成本、提升 PR 审查质量、增强文档自动化和改善 UI 资产可视化管理。
01
技术亮点
- 可以把 Compose 应用导航结构转成可交互的可视化地图，降低理解复杂业务流程的成本。
- 支持 Navigation 3、Navigation 2、其他 Compose 导航库以及普通 Activity，迁移门槛较低。
- 通过 KSP 静态提取导航信息，不依赖运行时埋点。
- 使用 Layoutlib 无设备渲染页面缩略图，不需要启动模拟器。
- 支持多模块导航图合并，适合大型 Android 工程。
- IDE 插件支持双击跳转源码、从图上添加 transition、创建 destination 等交互。
- 可以导出 HTML 或 PNG，方便放入 PR、技术文档、设计评审或团队 Wiki。
- 支持 @Preview Gallery，把项目中所有 Compose Preview 聚合成可浏览的图库。
- Apache-2.0 开源协议，商业项目使用相对友好。
- 作者 skydoves 在 Android / Compose 开源生态中较活跃，项目可信度较高。
02
目标用户
- 使用 Jetpack Compose 的 Android 开发者
- 维护复杂导航流的移动端团队
- 采用 Navigation 2 / Navigation 3 / 自定义导航方案的项目
- 多模块 Android 应用架构团队
- 需要在 PR 中审查页面跳转变化的技术负责人
- 需要生成应用流程图、设计评审材料或团队 Wiki 文档的开发团队
- 希望统一查看项目中所有 @Preview 的 UI / 设计系统团队
03
配置要求
- Android Studio 或 IntelliJ IDEA，需要安装 Compose Navigation Graph IDE 插件。
- 项目需要使用 Gradle，并配置 Maven Central、Google Maven 和 Gradle Plugin Portal。
- 需要 Kotlin 与匹配版本的 KSP 插件。
- Android 最低 API 标识为 24+。
- Compose 页面建议提供 @Preview，以便生成可视化缩略图。
- 需要在模块中应用 com.github.skydoves.navgraph Gradle 插件。
- 常用 navgraph 配置包括 renderThumbnails、variant、failOnNavChange、galleryEnabled。
- 如果项目有多个 flavor / build variant，可能需要通过 variant.set("demoDebug") 指定用于生成图的变体。
- 如果启用导航变更校验，需要提交 .nav baseline 或相关导航基线文件，以便 navCheck 对比。
04
适用场景
- 在 Android Studio 中以图形化方式查看整个 App 的页面流转关系
- 查看每个页面节点对应的 Compose @Preview 缩略图
- 查看路由类中的 typed arguments，帮助理解页面入参
- 多模块项目中合并各模块导航图，形成全局应用流程图
- 从导航图中双击节点跳转到对应源码
- 通过拖拽或右键菜单在 IDE 中添加页面跳转关系
- 自动生成 nav-graph.json 作为导航结构基线
- 在 CI 或 PR 中使用 navCheck 检测导航变更，避免未审查的页面或跳转变化
- 导出导航图为交互式 HTML 或 PNG，用于评审、文档和团队同步
- 生成项目内全部 @Preview 的预览图库，便于查看组件和页面状态
05
部署与配置
- 在 Android Studio 或 IntelliJ IDEA 中打开 Settings > Plugins > Marketplace，搜索 Compose Navigation Graph 并安装 IDE 插件。
- 确保 settings.gradle.kts 的 pluginManagement.repositories 中包含 google()、mavenCentral() 和 gradlePluginPortal()。
- 在包含 Compose 页面或路由定义的模块 build.gradle.kts 中应用 KSP 插件：id("com.google.devtools.ksp") version "<匹配 Kotlin 版本>"。
- 在同一模块中应用导航图 Gradle 插件：id("com.github.skydoves.navgraph") version "0.1.2"。
- 为页面添加注解，例如 @NavDestination、@NavEdge、@NavGraphRoot、@NavPreview。
- 运行 ./gradlew :app:generateNavGraph 生成导航图数据和页面缩略图。
- 在 IDE 中打开 View > Tool Windows > NavGraph Graph 查看 Graph、Previews 等标签页。
- 可选：运行 ./gradlew :app:generatePreviewGallery 生成所有 @Preview 的图库。
- 可选：运行 exportNavGraphHtml、exportNavGraphImage、exportPreviewGalleryHtml 或 exportPreviewGalleryImage 导出 HTML / PNG 产物。
06
风险与注意事项
- 项目当前 stars 约 399，生态仍处于较早期阶段，企业级长期稳定性需要实际验证。
- Gradle 插件版本示例为 0.1.2，说明项目可能仍在快速迭代，API 或配置方式可能变化。
- 需要在代码中增加注解，老项目接入时需要一定改造成本。
- KSP、Kotlin、Compose Compiler、Android Gradle Plugin 版本之间可能存在兼容性问题。
- 复杂项目中的自定义导航逻辑、动态路由、运行时条件跳转可能无法完全被静态分析覆盖。
- Layoutlib 渲染部分 @Preview 时可能遇到资源、主题、依赖注入或平台 API 兼容问题。
- 多模块、多 flavor 项目需要正确配置 variant，否则生成结果可能不完整。
- IDE 插件依赖 Android Studio / IntelliJ 插件环境，团队成员需要统一安装和维护。
- 如果将 .nav baseline 用于 CI，需要建立清晰的评审流程，否则可能造成误报或阻塞构建。
2026-06-19
第21名
新收录 · github_search
