APK 卡在「正在安装…」不动:PackageInstaller 会话机制与 adb 逐层排查
「正在安装…」这三个点转了十分钟,进度条不走、不弹错误、也取消不掉。多数人的第一反应是重启手机、清安装器缓存、再点一次安装,运气好能过,运气不好就陷入循环。这类问题之所以难查,是因为界面只给你一个转圈,而底下其实是一条有状态的安装流水线在某个环节停住了,系统既没判定成功,也没走到能给用户报错的那一步。
本文不再重复「清缓存、换安装包」这类通用建议,而是把 Android 的安装会话(PackageInstaller Session)拆开:它分哪几步、每一步由谁负责、卡住时会留下什么信号,以及怎么用 adb 把卡点精确定位到某一层。所有命令都可以直接复制执行。
先分清:卡的是下载、校验,还是安装会话
排查前先做一次归类,因为这三件事在界面上长得几乎一样,但处理方向完全不同。如果文件本身还没落盘,那属于下载问题,可以参照 APK 下载完找不到文件的逐层定位 或 下载中断与续传处理;如果浏览器提示「下载已完成」但文件随后消失,走 下载文件消失的排查路径。下面这张表只针对文件已经在手机上、点开后开始安装的情形。
| 界面表现 | 后台主要组件 | 正常耗时 | 卡住通常意味着 |
|---|---|---|---|
| 通知栏下载进度停在 99% | DownloadManager / 浏览器下载器 | 数秒到数分钟 | 文件未完整落盘,与安装会话无关 |
| 「正在检查…」或「正在扫描…」 | 包验证器、Play Protect、OEM 安全扫描 | 1–30 秒 | 验证器在联网取判定结果,网络或服务端超时 |
| 「正在安装…」转圈不动 | PackageInstaller 会话 + PackageManagerService | 2–60 秒 | create/write/commit 某一步阻塞,或 commit 后的 dexopt 卡住 |
| 「正在优化应用…」 | dex2oat / ART 编译 | 数秒到数分钟 | 编译大包时空间或 CPU 不足 |
| 进度条走完但立刻回到桌面 | 安装器 Activity 结束 | 瞬时 | 实际已失败,错误被 UI 吞掉,需要看 logcat |
一个很实用的判据:如果下拉通知栏还能看到下载进度,就还没进入安装会话;只有点开 APK、出现安装确认页之后,PackageInstaller 才真正开始工作。
安装会话到底是什么:一次安装被拆成了四步
从 Android 5.0(API 21)开始,系统用 PackageInstaller API 把「安装一个应用」建模成一个会话(session)。会话有唯一 ID、有状态、可以分多次写入数据,也可以被放弃。这个设计主要是为分包 APK 和大体积游戏服务的:先开一个会话,把 base.apk 和各个 split 流式写进去,最后一次性提交给系统。
理解这一步很关键,因为它解释了「为什么转圈时什么都没发生」——界面上的进度圈往往是在等待 commit 之后的批量处理,而写入阶段其实早就结束了。
| 阶段 | adb 对应命令 | 系统内部动作 | 这一步卡住的典型表现 |
|---|---|---|---|
| create | pm install-create -S <字节数> | 分配 session ID,在 /data 预留临时目录 | 空间不足时直接返回失败,很少转圈 |
| write | pm install-write -S <字节数> <id> base.apk | 把 APK 字节流写入会话暂存区 | 大包写入慢、/data 写满、USB 传输中断 |
| commit | pm install-commit <id> | 提交给 PackageManagerService | 最常见的转圈点:验证器、签名比对、权限授予都在这里 |
| post-commit | 无直接命令 | 解析清单、dexopt 编译、广播 PACKAGE_ADDED | 「正在优化应用」长时间不动 |
| abandon | pm install-abandon <id> | 丢弃会话、回收暂存文件 | 残留会话不清理会持续占空间 |
adb install 并不是另一套机制,它只是把这条 create → write → commit 链路封装成了一条命令。所以当你用 adb install 能装成功、点界面却卡住时,问题基本可以锁定在安装器 UI、验证器或 OEM 定制层,而不是包本身。反过来,如果 adb install 也卡在同一处,那就该往空间和 dexopt 方向查了。
五类根因与它们留下的信号
先把常见原因和对应证据列清楚,后面六步排查就是按这张表逐条排除。
| 根因 | 机制 | 可观察信号 | 定位命令 |
|---|---|---|---|
| /data 分区空间不足 | 会话暂存区与 dexopt 产物都需要空间,系统预留量通常大于 APK 体积 | logcat 出现 INSTALL_FAILED_INSUFFICIENT_STORAGE 或 dex2oat 写入失败 | adb shell df -h /data |
| 残留或僵死会话 | 上次安装被强杀,会话未 commit 也未 abandon,安装器继续等待 | dumpsys 里出现长时间未变化的 session 记录 | adb shell dumpsys package 查 session 段 |
| 验证器联网阻塞 | commit 阶段向云端查询证书与风险判定,弱网或服务端超时会长时间挂起 | logcat 出现 verification timeout、VERIFICATION_FAILURE | adb logcat -s PackageManager:V |
| 签名或版本冲突 | 同包名不同签名、降级安装,冲突在 commit 时才被完整判定 | INSTALL_FAILED_UPDATE_INCOMPATIBLE、SIGNATURE_MISMATCH | adb logcat -s PackageInstallerSession:V |
| 分包或 ABI 不匹配 | base.apk 缺失、split 与设备架构不符 | INSTALL_FAILED_MISSING_SPLIT、安装后立刻闪退 | adb shell getprop ro.product.cpu.abi |
| OEM 后台限制 / 安装器被杀 | 省电策略杀掉安装器进程,或限制后台安装 | 转圈后界面突然回到桌面,无任何错误 | adb shell dumpsys activity 查 installer 进程 |
注意「空间不足」这一项有个反直觉的地方:系统需要的可用空间大约是 APK 体积的 2–3 倍,因为要同时容纳会话暂存文件、安装后的 APK 副本以及 dexopt 编译产物。一个 1.2 GB 的游戏包,在只剩 1.5 GB 的手机上大概率会卡在 commit 或优化阶段。遇到体积问题,可以先看 APK 体积膨胀与存储回收 和 卸载后空间仍被占用的排查。
开始前:准备与只读采样
先把设备连上并做一轮只读采样,不要在还没证据的时候清数据或改设置。以下命令在 macOS、Linux、Windows 的 adb 环境下通用,含 grep 的部分如果在 Windows 上执行,请改用 adb shell "dumpsys package | grep -i session" 这种把管道放进 shell 的写法。
adb devices
adb shell getprop ro.build.version.release
adb shell getprop ro.build.version.sdk
adb shell getprop ro.product.cpu.abi
adb shell df -h /data
adb shell df -h /cache
adb shell dumpsys package | grep -i -A 30 "install session"
adb logcat -d -s PackageManager:V PackageInstallerSession:V | tail -80记录四个值:Android 版本、CPU 架构、/data 剩余空间、当前是否存在未结束的会话。这四项基本决定了后面该走哪条分支。如果设备还没打开 USB 调试,可以参照 离线安装前的准备工作;如果安装确认页根本弹不出来,先去核对 未知来源安装权限在各版本的变化。
六步排查路径
第 1 步:确认会话是否真的存在
先把日志缓冲区清掉,再重新触发一次安装,这样拿到的都是本次的记录。
adb logcat -c
adb logcat -s PackageManager:V PackageInstaller:V PackageInstallerSession:V &在另一个终端里点开 APK,回到日志窗口观察。如果连 createSession 之类的记录都没有,说明安装器根本没启动会话——问题在权限或 UI 层,而不是安装链路。如果出现了 session ID 但迟迟没有 commit,那就是会话被挂起了。不同 Android 版本 dumpsys 的字段名略有差异,可以用 adb shell dumpsys package | grep -i session 配合 adb shell cmd package help 查看当前版本支持的子命令。
第 2 步:核对空间,而不只是看「还剩多少 GB」
adb shell df -h /data
adb shell du -sh /data/app /data/local/tmp 2>/dev/null
adb shell pm trim-caches 1Gdf 看分区总量,du 看谁占了大头,pm trim-caches 让系统回收一部分缓存(它不会删你的应用数据)。如果 /data 剩余不足 APK 体积的 2 倍,先清理再重试,不要反复点安装。这一步也能顺带发现残留的会话暂存文件。
第 3 步:抓 commit 阶段的错误码
这是信息量最大的一步。保持日志监听,重新触发安装,重点找下面这些标记:
adb logcat -s PackageManager:V PackageInstallerSession:V | grep -i -E "install|verify|dexopt|failed|timeout"| logcat 关键字 | 含义 | 下一步 |
|---|---|---|
INSTALL_FAILED_INSUFFICIENT_STORAGE | 空间不足 | 回到第 2 步,清出 2–3 倍体积 |
INSTALL_FAILED_UPDATE_INCOMPATIBLE | 同包名签名不同或版本降级 | 先卸载旧包,或核对签名后重装 |
INSTALL_FAILED_VERIFICATION_FAILURE | 验证器判定不通过或超时 | 走第 6 步,检查网络与验证器状态 |
INSTALL_FAILED_DEXOPT | ART 编译失败 | 空间、SELinux 或包本身损坏 |
INSTALL_FAILED_MISSING_SPLIT | 分包不完整 | 走第 5 步 |
无任何 failed,只有长时间 commit | 等待外部判定或进程被挂起 | 走第 4 步手动重放 |
如果日志里出现了「安装成功」的广播但桌面仍然找不到图标,那已经不是安装问题了,请转去 装完桌面找不到图标的排查;如果能打开但立刻闪退,看 安装成功却启动崩溃。
第 4 步:手动重放一次会话,把卡点拆开
这是最直接的判定方法:绕过安装器 UI,用 adb 把四个阶段分别执行一遍,看是哪一条命令停住。
adb push app.apk /data/local/tmp/app.apk
SIZE=$(stat -f %z app.apk)
adb shell pm install-create -r -S $SIZE
adb shell pm install-write -S $SIZE <SESSION_ID> base.apk /data/local/tmp/app.apk
adb shell pm install-commit <SESSION_ID>
adb shell pm install-abandon <SESSION_ID>说明几点:stat -f %z 是 macOS 写法,Linux 请换成 stat -c %s;install-create 会返回一个数字,那就是要填进 <SESSION_ID> 的值;install-write 的第二个参数是会话内文件名,base 包固定用 base.apk;最后一条 install-abandon 只在会话失败或残留时执行,成功后不要跑。
如果 install-write 卡住,查 USB 连接和 /data 写入;如果 install-commit 卡住,查验证器和签名;如果三条命令都秒回成功,那么卡住的一定是安装器 UI 或 OEM 定制层,此时用 adb install -r app.apk 作为交付手段即可绕开。
第 5 步:分包 APK 要按正确顺序提交
从应用商店导出的现代应用常常不是一个文件,而是 base 加若干 split。用 adb install 只装 base 往往能装上但缺资源,或者干脆卡在 commit。
adb shell getprop ro.product.cpu.abi
adb shell getprop ro.product.cpu.abilist
adb install-multiple base.apk split_config.arm64_v8a.apk split_config.xxhdpi.apk
adb shell pm path com.example.app规则很简单:base.apk 必须排在第一位;只提交与 ro.product.cpu.abi 匹配的架构 split;密度 split 选一个即可。已经装上的包可以用 adb shell pm path <包名> 看到系统实际接收了哪些分片,用它反过来核对你提交的组合是否完整。
第 6 步:区分验证器与 OEM 限制
adb shell settings get global package_verifier_enable
adb shell settings get secure install_non_market_apps
adb shell dumpsys package com.google.android.gms | grep -i verify
adb shell dumpsys activity | grep -i installerpackage_verifier_enable 表示系统级包验证是否开启,install_non_market_apps 对应未知来源开关。这里只做判断,不建议为了装一个包长期关闭安全扫描:如果日志明确显示是 verification timeout,更合理的处理是切换到稳定网络、等待片刻后重试,或用第 4 步的 adb 链路交付。若 dumpsys activity 显示安装器进程被回收,检查该品牌的省电白名单与后台弹窗限制。
三个真实场景的完整走法
场景 A:点安装后转圈十分钟,logcat 显示 verification timeout。 第 1 步确认会话已创建并已写入,第 3 步抓到超时关键字,第 6 步确认验证器开启。处理:切到稳定网络重试;仍不行则用第 4 步的 adb 三连完成安装。不要反复点安装,那会叠加多个等待中的会话。
场景 B:adb install 返回 Success,但应用列表里没有。 这已经越过安装会话,属于启动器可见性问题,直接看 装完桌面找不到图标的排查。如果装完出现明显耗电异常,再参考 安装后耗电异常排查。
场景 C:大游戏包,空间显示够,卡在「正在优化应用」。 第 2 步按 2–3 倍体积重新估算,第 3 步查 dex2oat 写入失败,第 5 步确认 OBB 与 split 是否齐全。这类问题常伴随存储碎片,APK 瘦身与空间回收 里的顺序可以直接照搬。
常见错误做法
- 反复点安装:每次点击都可能新建一个会话,多个会话排队只会让转圈更久,还额外占用 /data 的暂存空间。
- 直接删 /data/app 下的目录:没有 root 的设备做不到,有 root 的设备则容易留下 PackageManagerService 的残留记录,后续安装更容易报签名冲突。
- 为了装一个包永久关掉所有安全扫描:把一次性的验证超时变成长期风险,验证器状态改完记得恢复。
- 用 `pm install -r` 强行覆盖签名不同的包:
-r只解决「已存在同签名旧版本」,跨签名必须先卸载,硬来只会得到UPDATE_INCOMPATIBLE。 - 把下载慢当成安装卡住:如果通知栏还有下载进度,方向完全相反,参考 下载限速来源的逐层测速法 一类思路先解决落盘问题。
FAQ
问:为什么「正在安装」一直转圈,却始终不报错?
因为系统还没走到能给出结论的那一步。commit 之后的验证、签名比对和 dexopt 都是异步的,只要外部判定没返回,安装器就保持等待态。logcat 里通常已经有线索,只是 UI 没把它翻译给用户。
问:重启手机能解决吗?
对「残留会话」和「安装器进程被杀」有效,因为重启会清掉未提交的内存态会话;对空间不足、签名冲突、分包缺失完全无效。更推荐先用第 1 步确认会话状态,再决定要不要重启。
问:adb install 和点击安装走的是同一套流程吗?
底层是同一套 PackageInstaller 会话,区别在入口:adb 直接调 create/write/commit,点击安装则多经过安装器 Activity 和包验证器。这正是「对比两者结果」能快速缩小范围的原因。
问:残留会话会一直占着存储空间吗?
会,直到被 commit 或 abandon。未提交的会话暂存文件留在 /data 下,设备重启通常会清理内存态记录,但已写入的临时文件未必立即回收。用第 4 步的 pm install-abandon <SESSION_ID> 是最干净的收尾方式。
问:分包 APK 为什么更容易卡住?
因为提交时要同时校验 base 与所有 split 的签名、版本和架构一致性,任何一片缺失或与设备 ABI 不符,commit 都会挂起或失败。先 getprop ro.product.cpu.abi,再按第 5 步的顺序提交,能避开绝大多数这类问题。
问:出现 verification failure,是不是文件被篡改了?
不一定。这个标记既可能是真实的签名或哈希不符,也可能只是验证器联网超时被归并成同一类结果。判断依据是文件本身的完整性核验,而不是单看这条日志。
问:卡住之后继续点安装会怎样?
多数情况下会新建一个会话并排队等待,转圈时间变长、/data 暂存空间被进一步占用。正确做法是先 adb logcat -c 清日志,单次触发、抓完整链路,再用 install-abandon 收尾。
小结
把「正在安装」当成一个可拆解的流水线,排查就有了固定顺序:先确认是不是安装阶段、查空间与会话状态、抓 commit 日志里的错误码、必要时手动重放 create/write/commit、核对分包组合、最后才考虑验证器与 OEM 限制。这六步下来,绝大多数转圈问题都能定位到具体一层,而不是靠重启碰运气。
延伸阅读:安装前的 未知来源权限设置、离线安装准备,安装后的 装完无图标、启动即崩溃、耗电异常,以及存储侧的 卸载后空间仍满 与 体积膨胀回收。