装完 APK 检测不到、拉不起别的应用:Android 11 包可见性与 queries 声明逐层排查
有一类故障特别容易被归咎于「下到了残缺版」:应用本身装得上、图标在、首页也刷得出来,可一点「用地图打开」「分享到微信」「调用相机扫码」「跳转支付」,要么毫无反应,要么弹出的候选列表里根本没有目标应用;更让人困惑的是,用电脑 adb 进手机敲 pm list packages,微信、地图、银行 App 一个不少,偏偏应用自己说「未安装」或者返回空列表。
于是很多人开始卸载重装、清数据、换下载源、找「完整版 / 解锁版」。但这些动作几乎都碰不到根因。系统里能列出这些包,说明包确实装了、也确实注册在系统里;应用看不到,是因为从 Android 11(API 30)开始,PackageManager 返回给每个应用的结果被按调用方身份过滤了。同一个查询,系统服务看到的是全集,你的应用看到的只是被允许的那一部分。
这不是 bug,是 Android 官方为了减少「应用偷偷枚举用户装了什么」而做的隐私加固。它对从应用商店安装的、按新规范适配过的应用几乎无感,却经常命中两类侧载包:一类是多年未更新、targetSdk 停留在 29 及以下的老应用(老 targetSdk 反而继承旧行为,但一旦被系统按新规则重新判定就会出岔子);另一类是targetSdk 升到 30 以上、却没有补 queries 声明的应用。更麻烦的是,同一个 APK 在 Android 10 手机上一切正常,换到 Android 12/13/14 就「分享列表空了」,于是被误判成系统兼容问题。
本文把这条链路拆开:先分清四种「拉不起来」,再用机制表格定位是哪一层在过滤,然后给出可以直接复制执行的 aapt / adb / curl 命令、九步排查路径、错误与状态速查、版本差异,最后是常见问题与站内延伸阅读。判断的核心动作只有两个:看这个包的 targetSdkVersion,以及用 `cmd package query-activities` 站在应用视角重放一次 intent 解析。
一、先分清四种「拉不起来」,别一上来就重装
包可见性问题的表现差异很大,但根因层不出这四类。先对号入座,能省掉大量无效操作:
- 第一类:候选列表为空或不全。点「分享」「用…打开」,选择器里只有一两个应用,或者干脆空白。典型于
queryIntentActivities()返回空集,是包可见性过滤最直接的表现。 - 第二类:明确报「未安装 / 找不到应用」。应用主动检查某个包名是否存在(比如「请先安装微信」提示),
getPackageInfo()抛NameNotFoundException,于是走到错误分支。包其实在,只是不在可见集合里。 - 第三类:点击后闪退或静默失败。应用没做空判断,直接
startActivity()一个解析不到组件的隐式 intent,抛ActivityNotFoundException未捕获就崩;或者内部吞掉异常表现为「点了没反应」。 - 第四类:特定能力失效,主流程正常。比如能打开应用、能登录,但「跳转到浏览器看协议」白屏、「拉起相机」失败、ContentProvider 查询返回 null。这类是 intent 签名 / provider authority 未声明进 queries 的细分情形。
需要立刻排除的干扰项:目标应用装在了另一个用户空间(工作资料、手机分身、隐私空间),此时主空间的应用确实看不到它,这属于多用户隔离而非包可见性,排查路径完全不同;以及目标应用被停用或卸载残留,pm list packages 加 -u 才列得出来。这两类在第五节的排查路径里都有对应的 adb 检查。
二、机制表格:过滤到底发生在哪一层
包可见性不是一个开关,而是一组按 targetSdk、声明方式、查询类型分层的规则。下表把常见情形逐条列出,「现象」一列可以直接拿来对照日志。
| 层 / 触发条件 | 系统行为 | 应用侧看到的结果 | 典型现象 |
|---|---|---|---|
| targetSdk ≤ 29 且系统为 Android 11+ | 沿用旧的宽松可见性(过渡兼容) | 基本能枚举全部已装包 | 老应用反而「正常」,新应用出问题 |
| targetSdk ≥ 30,清单无 queries 声明 | 只自动可见自身、系统组件、部分默认处理者 | queryIntentActivities() 大幅缩水 | 分享/选择器列表空或不全 |
清单声明 <queries><package android:name="..." /> | 该包名加入可见集合 | 能查到这一个包 | 指定合作方 App 可用,其他仍不可见 |
清单声明 <queries><intent> 签名 | 能解析匹配该 intent 的组件 | 能列出对应处理者 | 「用浏览器/地图打开」恢复 |
清单声明 <queries><provider android:authorities="..." /> | 该 authority 可见 | ContentProvider 查询不再返回 null | 跨应用数据读取恢复 |
申请 QUERY_ALL_PACKAGES 权限 | 系统不再过滤任何包 | 枚举全集 | 应用商店/清理类工具需要,Play 上架受限 |
| 系统自动可见的白名单 | 无需声明即可见 | 自身、安装器、浏览器默认项等 | 少数能力「碰巧能用」 |
pm list packages(adb shell 身份) | shell UID 不受过滤 | 输出全集 | 「电脑看得到、应用看不到」的错觉来源 |
| 目标包属于另一用户 UserHandle | 按用户隔离 | 主空间查询不到 | 需 --user 参数或 pm list users 判别 |
目标包被 pm disable / 卸载残留 | 状态非 ACTIVE | 解析被跳过 | pm list packages -d / -u 可查 |
| 隐式 intent 无匹配处理者 | 解析为空 | 抛 ActivityNotFoundException | 点击闪退或静默失败 |
| App Links 域名未验证 | 默认浏览器接管 | 目标应用不在候选里 | 需 assetlinks.json 校验 |
| OEM 定制(部分国产 ROM) | 额外限制「读取应用列表」权限 | 即使声明仍被拦 | 设置里需单独放行 |
这里最容易被误解的一点是:adb shell 里所有 pm / cmd package 子命令都以 shell UID 运行,不受包可见性过滤。所以「adb 列得出、应用列不出」非但不矛盾,恰恰是包可见性问题的确认信号。要站在应用视角复现,必须用 cmd package query-activities --userId 配合 --brief,或者用 am start 从 shell 发起一次真实解析(见第四节)。
三、targetSdk 才是那个总开关
为什么同一个 APK 在旧手机上好端端的,换台新机就坏了?因为过滤规则的启用条件是调用方应用的 targetSdkVersion,而不是系统版本的简单开关。
- targetSdk ≤ 29:系统为兼容旧应用,保留「能看到全部已装包」的旧行为。很多 2019 年前后停止维护的侧载包属于这一类,因此它们在 Android 14 上反而不会触发本问题。
- targetSdk ≥ 30:默认进入过滤模式。开发者必须在
AndroidManifest.xml里加<queries>逐项声明「我要看谁」,或者申请QUERY_ALL_PACKAGES。 - 关键点在于:升级 targetSdk 时如果忘了同步补 queries,功能就会静默退化。这正是「新版侧载包装完拉不起别的应用」的高发原因,而且不会有任何安装期报错——安装成功、启动成功,只在跨应用调用时露馅。
还有一层叠加因素:Android 12 起 android:exported 必须显式声明,Android 13 起通知权限、Android 14 起更严的前台服务与精确闹钟策略陆续收紧。这些与包可见性彼此独立,但都会表现为「装完某些功能不工作」。排查时若发现 queries 已声明仍失败,要按版本差异表(第七节)逐项排除,而不是回头怀疑包完整性。
四、可直接执行的命令清单
以下命令全部在电脑侧通过 adb 执行,或直接对 APK 文件执行,不需要 root。把 <pkg> 换成出问题应用的包名(如 com.example.app),把 <apk> 换成本地 APK 路径。
# 1. 确认设备已连接、拿到准确的包名
adb devices
adb shell pm list packages | grep -i example
adb shell pm path com.example.app
# 2. 最关键一步:读 targetSdkVersion,判断是否在过滤模式
aapt dump badging app.apk | grep -E "package:|sdkVersion:|targetSdkVersion:"
# 若无 aapt,用 apkanalyzer(Android SDK cmdline-tools)
apkanalyzer manifest application-id app.apk
apkanalyzer manifest target-sdk app.apk
# 3. 直接把 queries 声明从二进制清单里 dump 出来
aapt dump xmltree app.apk AndroidManifest.xml | grep -i -A6 -B2 "queries\|package\|intent\|provider"
# 或用 apkanalyzer 打印合并后的清单
apkanalyzer manifest print app.apk | grep -i -A10 "<queries"
# 4. 站在应用视角重放一次 intent 解析(核心复现手段)
adb shell cmd package query-activities --brief -a android.intent.action.VIEW -d "https://www.example.com/page"
adb shell cmd package query-activities --brief -a android.intent.action.SEND -t "text/plain"
adb shell cmd package resolve-activity --brief -a android.intent.action.VIEW -d "https://www.example.com/page"
# 5. 查看某应用实际被授予的可见性与声明
adb shell dumpsys package com.example.app | grep -i -A20 "queries\|QUERY_ALL_PACKAGES\|visibility"
adb shell appops get com.example.app QUERY_ALL_PACKAGES 2>/dev/null || true
# 6. 排除多用户 / 停用 / 卸载残留造成的「假不可见」
adb shell pm list users
adb shell pm list packages --user 0 | grep -i wechat
adb shell pm list packages -d # 被禁用的包
adb shell pm list packages -u # 含卸载残留
adb shell cmd package dump com.example.app | grep -i "userId\|enabled"
# 7. 抓解析失败日志,定位异常类型
adb logcat -c && adb logcat -s PackageManager ActivityManager AndroidRuntime | grep -i -E "not found|ActivityNotFound|NameNotFound|query|visibility"
# 8. 手动发起一次启动,验证是否抛 ActivityNotFoundException
adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/page"
# 9. App Links 域名验证(若怀疑是链接归属而非可见性)
adb shell pm get-app-links com.example.app
curl -sSI "https://www.example.com/.well-known/assetlinks.json" | head -20
# 10. 对照:同一 intent 在另一台 targetSdk 不同的设备上的解析结果
adb shell cmd package query-activities --brief --user 0 -a android.intent.action.SENDTO -d "smsto:10086"几点使用说明。query-activities 的 -a 指定 action、-d 指定 data URI、-t 指定 MIME type、-c 指定 category,可以叠加;--brief 让输出只留组件名,便于比对。第 3 步的 aapt dump xmltree 在部分新版 SDK 里对 <queries> 节点输出不稳定,此时改用 apkanalyzer manifest print 更可靠。第 9 步的 curl 用于从电脑侧确认服务端 assetlinks.json 是否返回 200 且包含正确指纹——因为「目标应用不在候选列表」有时根本不是可见性问题,而是 App Links 验证没过。
五、九步排查路径
按顺序做,任何一步定位到根因就可以停止,不必走完九步。
- 确认现象属于四类里的哪一类:列表空、报未安装、闪退、还是特定能力失效。若是「另一用户空间装的应用」,直接跳到第 8 步。
- 读 targetSdkVersion:用
aapt dump badging或apkanalyzer。≤ 29 基本可排除包可见性为主因,转去查签名、ABI、组件导出;≥ 30 继续。 - dump 清单里的 queries:确认有没有声明、声明的是包名、intent 签名还是 provider authority。完全没有任何
<queries>且又没申请QUERY_ALL_PACKAGES,基本可以定性。 - 用 query-activities 复现:把应用实际发起的 intent 原样重放,看系统返回几个候选。返回空 = 解析层问题;返回多个但应用只显示一个 = 应用层过滤逻辑问题。
- 看日志异常类型:
NameNotFoundException指向主动查包,ActivityNotFoundException指向直接启动隐式 intent,SecurityException指向权限/导出组件。三者处理方式不同。 - 排除目标应用状态:
pm list packages --user 0、-d、-u三项对照,确认目标包处于启用状态且在当前用户空间。 - 检查 App Links 与默认角色:
pm get-app-links看域名验证状态;若链接类跳转失败,另查cmd role holders android.app.role.BROWSER。 - 排除多用户隔离:
pm list users若存在第二个用户/工作资料,用--user <id>重放查询,判断是否是「装错空间」。 - 做版本对照:同一 APK 在两台不同 Android 版本(或不同 targetSdk 构建)设备上对比,确认问题是否随系统版本出现;随后决定是换用适配过的新版本,还是由使用方在设置里放行「读取应用列表」类 OEM 权限。
六、错误与状态速查表
| 现象 / 日志关键字 | 归属层 | 含义 | 下一步 |
|---|---|---|---|
NameNotFoundException | 主动查包 | 目标包不在可见集合或确实未装 | 第 3、6 步 |
ActivityNotFoundException | intent 解析 | 无匹配处理者或未捕获异常 | 第 4、5 步 |
queryIntentActivities 返回 size=0 | 可见性过滤 | queries 未声明或签名不匹配 | 第 3、4 步 |
SecurityException: ... exported | 组件导出 | Android 12+ 未显式声明 exported | 查目标应用清单 |
Permission denied / appops 拒绝 | OEM 权限 | 国产 ROM 额外限制读取应用列表 | 设置里单独放行 |
pm list packages 有、应用查不到 | 正常过滤 | shell UID 与 应用 UID 视角差异 | 用 query-activities 复现 |
QUERY_ALL_PACKAGES 已在清单 | 权限声明 | 系统不再过滤(Play 上架受限) | 确认是否被 ROM 拦截 |
assetlinks.json 404 / 指纹不匹配 | App Links | 域名验证失败,浏览器接管 | 第 9 步 curl 核对 |
| 只在 Android 11+ 复现 | 版本门槛 | targetSdk ≥ 30 触发过滤 | 第七节对照 |
| 换旧版本 APK 后恢复 | 构建差异 | 新版漏补 queries 声明 | 换用适配版本或反馈开发者 |
七、版本差异速查
| Android 版本 | 与包可见性相关的关键变化 | 对侧载包的现实影响 |
|---|---|---|
| Android 10(API 29)及以下 | 无过滤,可枚举全部已装包 | 老应用行为基准线 |
| Android 11(API 30) | 引入 package visibility,targetSdk ≥ 30 默认过滤;新增 <queries>、QUERY_ALL_PACKAGES | 问题开始出现的分水岭 |
| Android 12(API 31) | android:exported 必须显式声明;intent-filter 组件不声明即安装失败 | 与可见性叠加,易混淆 |
| Android 13(API 33) | 通知运行时权限、更细的组件可见性策略 | 「装完不通知」与「拉不起」并发 |
| Android 14(API 34) | 对 targetSdk < 23 的安装拦截、更严的前台服务限制 | 老包可能连装都装不上 |
| Android 15/16 | 延续过滤模型,Play 对 QUERY_ALL_PACKAGES 审核更严 | 侧载包更依赖精确 queries 声明 |
八、常见问题 FAQ
Q1:把 APK 重装一遍有用吗?
没有用。包可见性由清单声明与系统策略决定,重装不会改变清单内容,也不会重置系统对调用方的过滤规则。
Q2:清应用数据 / 缓存能解决吗?
不能。过滤发生在 PackageManager 查询层,每次调用实时判定,与本地缓存无关。
Q3:为什么 adb 里看得到,应用里看不到?
因为 adb shell 以 shell UID 运行,不受包可见性过滤;应用以自身 UID 运行,看到的是过滤后的子集。这个差异本身就是诊断依据。
Q4:给应用开「读取应用列表」之类的权限有用吗?
在部分国产 ROM 上有用——它们在此之上加了 OEM 层限制,需要在设置里单独放行。但在原生 Android 上,普通权限无法绕过包可见性过滤,必须由应用自己在清单里声明 queries。
Q5:换个旧版本 APK 是不是最省事?
如果旧版本 targetSdk ≤ 29 且功能够用,确实能绕开过滤,这是可行的临时方案;但老 targetSdk 在 Android 14+ 会面临安装拦截与后续兼容性风险,长期看应换用开发者适配过 queries 的新版本。
Q6:`QUERY_ALL_PACKAGES` 能不能自己加上去?
清单属于 APK 内部文件,修改后签名会变化,属于重打包,会破坏与原包的签名一致性并可能引入安全风险,不建议普通用户自行操作;更不要为此找来路不明的「已解锁版」。
Q7:怎么区分「包可见性」和「App Links 验证失败」?
两者都表现为目标应用不出现在候选里。判别方法是 pm get-app-links <pkg> 看域名验证状态,并用 curl 核对 /.well-known/assetlinks.json;若域名是 verified,则回到 queries 声明排查。
Q8:分享列表里少了一两个应用,也算这个问题吗?
算,而且是最典型的表现。系统只把匹配该 intent 且对调用方可见的处理者列出来,缺哪个往往就对应 queries 里少声明的那一类 intent 签名。
Q9:目标应用装在工作资料里,主空间应用能看到吗?
不能,这是多用户隔离而非包可见性。pm list users 会显示多个 UserHandle,pm install 默认只作用于当前用户,需要用 --user 指定。这类问题的排查链路完全不同。
Q10:什么时候该判定为「APK 本身坏了」,停止排查?
当 aapt dump badging 读不到 targetSdk、清单解析报 INSTALL_PARSE_FAILED、日志稳定出现 Signature mismatch 或 native 库 UnsatisfiedLinkError 时,问题已不在这条链路上,应转向包完整性、签名与 ABI 方向。
九、延伸阅读
下面这些站内文章与本文的排查链路相邻,可按需跳转:
- 装完 APK 点链接仍跳浏览器:App Links 域名验证与链接归属
- 侧载 APK 设为默认应用不生效:默认角色资格与 intent-filter
- 装完 APK 内嵌网页白屏:内嵌 WebView 与外部跳转的差异
- 工作资料、手机分身装不进 APK:多用户隔离与 pm install --user
- 装完 APK 桌面找不到图标:导出组件与启动器入口
- 装完 APK 启动即闪退:用 logcat 区分崩溃与解析失败
- APK 下载完找不到文件:分区存储视角下的文件可见性
- targetSdkVersion 说明:为什么它是这么多策略的总开关
- Android 14/15 侧载变化:新系统对老 targetSdk 的安装拦截
- APK 安装错误码速查:排除安装期错误后再谈运行期行为
- APK 通知不显示排查:另一类「装完功能不全」的常见根因
- XAPK / APKS / APKM 安装指南:分包场景下 base.apk 缺失能力
小结
「装完拉不起别的应用」不是包残缺,而是 Android 11 之后 PackageManager 按调用方身份做过滤的结果,触发条件是应用自身 targetSdk ≥ 30 且清单没补 queries 声明。排查的关键动作只有两个:用 `aapt dump badging` 读出 targetSdkVersion,以及用 `cmd package query-activities --brief` 把应用发起的 intent 重放一遍。前者确定是否进入过滤模式,后者确定解析层到底返回了什么。确认是清单缺失后,别在手机上反复重装——要么换用开发者适配过的版本,要么接受这是该构建自身的能力边界。