是时候迁移至AndroidX了！
长久以来，我们致力于做到三件事: 实践指南、减少模板代码和简化任务流程，我们希望帮助开发者们集中精力专注在真正需要考虑的逻辑中去。Jetpack 为此而生，它所包含的库、工具和指南，可以帮助您更轻松地编写高质量的应用。Jetpack 和 AndroidX 有什么关系呢? Jetpack 中所有库都使
长久以来，我们致力于做到三件事: 实践指南、减少模板代码和简化任务流程，我们希望帮助开发者们集中精力专注在真正需要考虑的逻辑中去。Jetpack 为此而生，它所包含的库、工具和指南，可以帮助您更轻松地编写高质量的应用。
Jetpack 和 AndroidX 有什么关系呢? Jetpack 中所有库都使用 AndroidX 作为包名，我们把 AndroidX 作为一个开发、测试和发布 Jetpack 库的开源工程。
在 2018 年的 I/O 大会上我们宣布了把 Support Library 重构至 AndroidX 命名空间的计划。在 Support Library 28，我们完成了重构，并且发布了 AndroidX 1.0。为了能够享受 Jetpack 所带来的便利，您需要将旧的 Support Library 迁移至 AndroidX。
为什么有必要迁移至 AndroidX
您可能会想: 既然 AndroidX 只是 Support Library 28 的重构，那为什么要迁移呢? 关于这个问题，我们有下面几个理由:
Support Library 已经完成了它的历史使命，28 将会是它的最后发布版。我们接下来将不会继续在 Support Library 中修复 bug 或发布新功能;
更好的包管理: 独立版本、独立命名以及更高频率的更新。以上优点，AndroidX 开箱既得;
目前已经有许多我们耳熟能详的工具库已经迁移至 AndroidX，例如 Google Play 服务、Firebase、Butterknife、Mockito 2、SQL Delight，我们后面会提到如何迁移它们的依赖;
我们正在努力推广 AndroidX 命名空间，未来所有新推出的组件库，例如 Jetpack Compose 和 CameraX，都将成为 AndroidX 的一员。
如何迁移至 AndroidX
前期准备
在开始迁移之前，为了使接下来的工作可以更加顺畅平滑，我们希望您可以做到以下几点:
首先，备份整个工程。大部分开发者都在使用 代码版本控制系统，但由于迁移工作牵扯到大量的文件修改，建议您备份整个工程;
其次，我们希望您尽量减少同时进行的功能开发;
最后还是建议您: 在单独的分支进行迁移工作。
开始迁移
在整个迁移步骤中，我们将着重于解决错误，使您的应用编译并通过所有测试。
下面是迁移工作的流程示意图，虽然步骤不少，但是本文会对其中的每一步都做出说明:
第一步: 将 Support Library 升级至 28
首先，我们建议您将当前的Support Library依赖升级至版本28。若您从早期版本的Support Library迁移，可能会面临API不兼容的问题，同时需要修改命名空间；而Support Library 28的API与AndroidX仅在命名空间上有所不同。因此，我们建议您先尝试将Support Library升级至版本28，处理所有API变更，并确保编译通过后，再进行下一步，这样能使修改量最小化。
第二步: 开启 Jetifier
接下来需要做的是开启 Jetifier。Jetifier 可以帮助您迁移第三方依赖库的依赖至 AndroidX。正如字面意思所说，Jetifier 会修改这些第三方依赖库的代码，从而使其与使用 AndroidX 的工程兼容。不过 Jetifier 不会修改您的源码和自动生成的代码，因此不用担心它会造成额外的不良影响。
开启 Jetifier 十分的简单，您只需要在 gradle.properties 文件中加入 "android.useAndroidX = true" 和 "android.enableJetifier = true" 即可。"useAndroidX" 设置用于开启 AndroidX 库的自动导入，当您自动补全或导入依赖库时，会自动导入 AndroidX 库。
第三步: 检查第三方库版本的兼容性
当您开启 Jetifier 之后，就要着手升级第三方依赖库到兼容的版本。在您真的开始迁移之前，最好把所有依赖升级到最新。
为什么要这么做? 其实我们自己就在这方面 "栽过跟头"，我们有一个演示应用: Plaid，它依赖了图片加载库 Glide，我们本来打算使用 Plaid 来演示如何迁移应用至 AndroidX，但当我们在没有检查 Glide 依赖库版本就开始迁移时，我们遭遇了一堆编译错误。检查后才发现，当时依赖的那个版本的 Glide 无法兼容 AndroidX。
然而，当我们将Glide以及其他依赖库的版本全部升级后，再去进行迁移工作，相同的错误就不再出现了。所以说，在着手迁移之前，建议先对应用的第三方依赖进行检查和升级，毕竟新版本的第三方库很可能已经对AndroidX进行了兼容。要知道，Jetifier可不会帮您迁移那些自动生成代码的依赖库，因此您还是得亲自去检查这类依赖是否与AndroidX兼容。
如果跳过了前面两步，您可能会遇到一些问题:
- 如果您当前使用的第三方库不兼容 AndroidX，您将会看到它依然在尝试拉取旧版本的 Support Library;
- 而如果您的工程被部分迁移，可能还会遇到类型重复的错误，这是因为工程正在尝试从 Support Library 和 AndroidX 拉取相同的代码。
第四步: 将 Support 库依赖转换为 AndroidX
这一步开始前，您应该完成了前面三个步骤: 升级 Support Library 到 28 版; 开启 Jetifier; 升级和检查第三方依赖库。确定这些都没问题后，我们终于可以开始真正的迁移工作了。这一步有以下三个方法供您参考:
- 使用 Android studio 自动迁移工具
我们在 Android 3.2 稳定版中加入了 "Migrate to AndroidX" 选项，方便大家迁移。您可以在 "Refactor" 菜单中找到 "Migrate to AndroidX" 选项:
这个按钮的功能，就是迁移源码中的依赖到 AndroidX，理想情况下，它会帮您完成绝大部分工作。
- 使用自动迁移脚本
我们也意识到有些团队使用的不是 Android Studio，而且也会有一些应用的结构过于复杂，使我们的工具无法生效。
所以还有两种选择，其中之一便是使用 bash 脚本中的 grep 和 sed 命令。在介绍如何使用脚本进行迁移之前，我们要特别感谢 Dan Lew 为我们提供了这个工具。
您可以通过短链接: goo.gle/androidx-migration-script 去到脚本源码的 GitHub 页面，在那里您也可以找到更多的社区贡献内容。
脚本的工作原理并不复杂，如下所示，您需要手动做的是配置好类型映射表 "androidx-class-mapping.csv" 和工程路径地址，而脚本中真正有效的部分，就只是 grep 命令后跟着一个 sed 命令来替换工程中导入的包名:
由于脚本的处理十分简单粗暴，所以可能会在某些情况下造成一些错误。使用这种方式一定要自己心里有数。
- 人工迁移
另一个选择，是人工进行迁移工作。在 迁移到 AndroidX 中，您能看到前文提到过的 Support Library 与 AndroidX 的类型映射关系表。如下图，有了这个映射关系表，您就可以根据具体情况进行替换:
这一步做完之后，只要您重新编译工程，并且修复那些迁移工作中损坏的测试，就可以获得一个基于 AndroidX 的工程。可喜可贺！
可能遇到的问题
当然，真实的情况往往不会那么一帆风顺。下面我们收集了一些迁移过程中常见的问题，希望能帮到您。
常见的需要手动处理的情况
以下图为例，我们看到这里依赖的仍然是 Support Library，其中 drawerLayout 和 recyclerview 的版本是用一组变量设置的:
遇到这种情况时，自动迁移不会理会您之前的变量配置，它会直接把这些库替换成一个确定的 AndroidX 版，如果您仍然想要使用变量管理这些库的版本号，就需要手动把 AndroidX 的依赖库版本改为使用变量设置。
自动迁移工具也不会修改您的混淆文件和构建脚本。如果这些文件中包含相关的包名，您需要手动去把它们改好。
冲突处理
我们前面有提到，一定要在一个新的分支中处理迁移工作，关于这点还有一些和大家分享的内容。
由于迁移工作会修改大量的文件，所以我们建议减缓或停止手头的开发工作。虽然要求整个开发团队停工听起来十分离谱，但是这样确实可以大大减少可能产生的合并冲突。
退而求其次的话，如果条件允许，最好能安排一些人手在一个单独的分支上专注于迁移的工作。与此同时，也要向团队中的其他成员预警即将到来的合并冲突。
在迁移依赖时，要专注于错误的修改，以编译成功和通过所有测试为首要目标。不要在迁移的同时进行重构或者引入新的功能。
检查自动迁移工具导入的库版本
当您运行完自动迁移功能后，您可能会发现新的依赖库中既有稳定版，又有 Alpha 版。这其实取决于我们最新发布的版本。您需要手动修改这些依赖库的版本，以满足自己工程的特定需要。
文档资源
我们总结了一些与本文相关的文档放在最后，来方便您回顾和查找。
AndroidX 概览 包括: AndroidX 总览、迁移指南以及 Support Library 到 AndroidX 库稳定版和 Alpha 版的映射关系表。如果您想要使用脚本处理迁移，这里也提供映射关系表的 CSV 文件。
我们有一篇文章介绍 Kotlin & Jetpack 实践技巧: 把 "格子衫" 改造得更时尚，描述了示例工程 Plaid 迁移至 AndroidX 的过程。在这篇文章中，我们说明了迁移的步骤，遇到的问题和对应的解决方案。
我们还提供了 问题追踪页，您可以在这个页面看到我们正在解决的问题，也可以通过左上角的按钮建立新的问题给我们。
祝大家都能顺畅地迁移至 AndroidX!
您也可以通过视频回顾 2019 Android 开发者峰会演讲 —— 是时候迁移至 AndroidX 了!
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。
Mountain Duck 是一款能将多个网盘挂载到本地的工具，像本地磁盘一样使用网盘。清理链路的完整性会更好一些，做应用卸载、残留处理和空间整理时，通常能少走很多手动排查步骤。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
Wise Folder Hider Pro 是一款专业级文件和文件夹隐藏加密软件，为私密数据添加多重保护。高频操作更强调就近处理，浏览、整理和跨目录移动文件时，来回切换和重复点击都会少很多。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。