装完 APK 点链接还是跳浏览器:Android App Links 验证机制与 assetlinks.json 逐层排查
有一类问题特别容易让人怀疑自己装了个假的 APK:应用明明装上了,图标在桌面上,手动点开一切正常,登录、刷新、推送都对,可只要从微信、短信或者浏览器里点一条 https:// 链接,系统要么直接扔给浏览器,要么弹出「打开方式」选择框,而框里压根没有这个刚装好的应用。
于是很多人开始重复卸载重装、清缓存、换下载源,甚至去找「修复版」重装一遍。但这类操作和问题的根因基本无关。应用能启动,说明安装环节是成功的;链接不跳转,说明另一条完全独立的链路没有打通——Android 的 App Links 域名验证。
> 核心判断:「安装成功」和「链接归属」是两套机制。前者由 PackageManager 负责,装完就结束;后者由系统在后台向应用官网发起一次 HTTPS 请求,比对包名和签名证书指纹,验证通过才把该域名判给这个应用。只要中间任何一环对不上,链接就永远轮不到你的 App。
这篇文章把这条链路拆开,给出每一步可以自己验证的命令,最后再说明哪些情况其实不是你的设备能修的。
一、先分清三个概念:Deep Link、App Link、以及系统「默认打开」
很多人把这几个词混着用,导致排查方向一开始就偏了。它们的区别决定了你会看到哪一种现象。
| 类型 | 系统如何判定 | 点链接时的现象 | 谁来决定 |
|---|---|---|---|
| 普通 Deep Link | 只匹配 manifest 里声明的 scheme / host,不校验网站所有权 | 弹出「打开方式」选择框,App 与浏览器并列 | 应用自己声明即可 |
| Android App Link | intent-filter 带 android:autoVerify="true",系统去站点拉 assetlinks.json 比对包名与签名指纹 | 验证通过后直接进 App,不弹选择框 | 网站 + 应用签名 + 系统共同决定 |
| 用户「默认打开」开关 | 设置里的「打开支持的链接」被关闭或域名未勾选 | 即使验证通过,也直接交给浏览器 | 用户手动设置 |
关键在中间那一行:App Link 的验证需要应用方网站配合。它不是一个纯本地设置,你在手机上怎么清数据都改不了服务器上的文件。这也是为什么侧载安装的场景格外容易踩坑——你手里的 APK 和官网声明的证书,未必是同一份签名。
还有一个容易误判的现象:如果点链接时弹出了选择框且能看到你的 App,那说明 intent-filter 是正常的,只是没有拿到「已验证」状态,属于 App Link 降级成了普通 Deep Link。如果选择框里完全没有你的 App,那问题更靠前,是 intent-filter 压根没匹配上,或者根本没声明 BROWSABLE。这两种情况的排查起点完全不同,先花十秒确认一下属于哪种。
二、验证链路到底发生了什么
从 Android 6.0(API 23)开始,一次 App Links 验证大致按下面的顺序走。理解顺序比背命令重要,因为每一步失败都对应一个不同的可观测信号。
| 阶段 | 触发时机 | 系统做什么 | 失败时的表现 | 可观测位置 |
|---|---|---|---|---|
| 1. 解析声明 | 安装 / 更新时 | 读取 manifest,找出带 autoVerify="true" 且含 VIEW、BROWSABLE、DEFAULT 的 intent-filter | 选择框里没有该 App | apkanalyzer manifest print |
| 2. 收集域名 | 紧接上一步 | 提取所有 android:host,过滤掉 http 之外的 scheme | 部分域名生效、部分不生效 | pm get-app-links 的域名列表 |
| 3. 发起验证 | 联网后异步执行 | 对每个 host 请求 https://<host>/.well-known/assetlinks.json | 长时间停留未验证状态 | 服务端访问日志、pm get-app-links |
| 4. 校验声明 | 拿到响应后 | 检查 HTTP 200、Content-Type、无重定向、JSON 合法、relation 与 package_name 匹配 | legacy_failure 或验证失败 | curl -sSI |
| 5. 比对指纹 | 紧接上一步 | 把 sha256_cert_fingerprints 与设备上已装应用的签名证书比对 | 前四步全过,仍显示未验证 | apksigner verify --print-certs |
| 6. 落库生效 | 验证完成 | 把域名标记为 verified,写入域名首选表 | 需要重新触发才更新 | pm get-app-links、dumpsys package |
| 7. 用户开关 | 点击链接时 | Android 12 之后还要看「打开支持的链接」是否允许 | 验证通过却仍跳浏览器 | 应用详情页设置 |
第 3 步有个常被忽略的前提:验证是系统后台发起的,不是你的浏览器。如果设备当时没联网、处于省电限制、或者域名解析被拦截,验证会静默失败并保持旧状态,不会给你任何提示。这也是「装完当时不行,过一会儿重启又好了」这类玄学现象的来源。
第 5 步是本站读者最该留意的一环。sha256_cert_fingerprints 比的是签名证书的 SHA-256 指纹,不是 APK 文件的 SHA-256,也不是应用版本号。很多人拿下载页标注的文件校验值去对,当然永远对不上。
三、assetlinks.json 长什么样,以及 Play App Signing 为什么是最大的坑
标准的声明文件放在站点根目录下的固定路径,内容是一个 JSON 数组:
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": [
"AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77"
]
}
}
]对它的要求比看上去严格,任何一条不满足都会让验证直接判失败:
- 必须通过
https://提供,TLS 证书链完整有效,自签名证书不行; - 必须返回 HTTP 200,不能有任何重定向(
http → https、不带 www → 带 www的重定向同样算失败); - 建议
Content-Type: application/json; - 不能被
robots.txt屏蔽,不能要求登录、Cookie 或客户端证书; - 必须是合法 JSON 数组,
relation用delegate_permission/common.handle_all_urls; namespace为android_app,package_name必须与设备上包名逐字一致;- 文件要在合理时间内返回,体积不宜过大(系统对验证请求有超时预算)。
现在说最隐蔽的坑。绝大多数上架 Google Play 的应用都启用了 Play App Signing:开发者用「上传密钥」签名后传上去,Google 会用另一把「应用签名密钥」重新签名再分发。因此官网 assetlinks.json 里填的,往往是 Google 那把应用签名密钥的指纹。
这意味着:
- 如果你从应用商店渠道装的是官方分发包,指纹一致,验证能过;
- 如果你侧载的是开发者内测包、调试包、旧版本、被重新签名的修改包,或来自不同分发渠道的包,签名证书不同,指纹必然不匹配;
- 结果是前面四步全部正常、文件也能拉到、包名也对,唯独第 5 步静默失败。
而且这个失败不会导致安装报错。签名不匹配只影响「更新同名应用」和「App Links 归属」,前者会报 INSTALL_FAILED_UPDATE_INCOMPATIBLE,后者则是完全无声的降级。所以你会看到.App 一切正常、只有链接不跳——这正是本文开头那个现象的典型成因。
如果你在对比不同来源的安装包,可以顺带读一下 APK 签名不一致导致安装失败的排查,那里讲的是同一套证书机制在安装阶段的另一种表现。
四、九步排查路径(每步都有可执行命令)
下面按顺序做,不要跳步。前四步在电脑上做,后五步需要 adb 连接设备(开启开发者选项与 USB 调试,或用无线调试)。所有命令里的 com.example.app 与 example.com 请替换成实际应用包名和域名。
第 1 步:确认 intent-filter 到底怎么声明的
先从 APK 里读 manifest,看有没有 autoVerify、BROWSABLE 和 DEFAULT:
apkanalyzer manifest print app.apk | grep -A 12 -i "intent-filter"
# 需要看到 android:autoVerify="true"、android.intent.category.BROWSABLE
# 以及 <data android:scheme="https" android:host="example.com" />如果没有 apkanalyzer,用 aapt 直接解二进制 XML:
aapt dump xmltree app.apk AndroidManifest.xml | grep -A 20 -i "autoVerify\|BROWSABLE\|android:host"判定:完全没有 autoVerify → 这应用本来就不打算做 App Link,点链接弹选择框是设计如此,不是故障。有声明再往下走。
第 2 步:确认设备上的实际包名
adb shell pm list packages | grep -i example
adb shell pm path com.example.app包名带 .debug、.beta 后缀,或者和你以为的不一样,都会让第 4 步的文件比对失效。顺带记下 pm path 返回的路径,第 5 步要用到。
第 3 步:从服务端拉取声明文件
curl -sSI https://example.com/.well-known/assetlinks.json
curl -sS -o /dev/null -w "code=%{http_code} type=%{content_type} redirect=%{redirect_url}\n" https://example.com/.well-known/assetlinks.json
curl -sS https://example.com/.well-known/assetlinks.json | jq .第一条看响应头,第二条把状态码、类型和重定向一次性打出来,第三条确认 JSON 能解析。任何 301 / 302、非 200、`text/html` 类型、`jq` 报错都直接判失败,不用再往设备侧查了。
第 4 步:取出你手里 APK 的签名证书指纹
apksigner verify --print-certs app.apk
# 输出示例:Signer #1 certificate SHA-256 digest: aabbccdd...
keytool -printcert -jarfile app.apk # 仅对 v1 签名有效的旧办法apksigner 输出的是不带冒号的连续十六进制;assetlinks.json 里通常写成带冒号、大写的分组形式。比对时统一转成同一种格式:
apksigner verify --print-certs app.apk | grep "SHA-256" | awk '{print $NF}' \
| tr 'a-f' 'A-F' | sed 's/../&:/g;s/:$//'拿这串和 jq -r '.[].target.sha256_cert_fingerprints[]' 的输出逐字对比。不一致就是根因,不必再折腾设备。
第 5 步:读取系统记录的域名验证状态
Android 12(API 31)及以上:
adb shell pm get-app-links com.example.app输出里每个域名后面会跟状态,常见值含义如下:
| 状态 | 含义 | 下一步 |
|---|---|---|
verified | 验证通过,域名已判给该应用 | 去第 8 步查用户开关 |
none / 1024 | 尚未验证或验证未完成 | 去第 6 步重新触发 |
legacy_failure | 服务端文件或声明不满足要求 | 回第 3、4 步 |
denied / 未列出 | 用户或系统显式不允许 | 去第 8 步 |
Android 11 及更早版本没有 pm get-app-links,用域名首选表:
adb shell dumpsys package domain-preferred-apps
adb shell dumpsys package com.example.app | grep -i -A 10 "domain\|verification"第 6 步:重新触发验证
adb shell pm verify-app-links --re-verify com.example.app
sleep 5
adb shell pm get-app-links com.example.app触发前确认设备联网、未开启极端省电、DNS 正常。验证是异步的,等几秒再读状态。如果始终停留在未验证,且第 3、4 步都正常,那基本可以断定是指纹不匹配(服务端声明的是另一把签名密钥),这是侧载分发包的固有结果,本地改不了。
第 7 步:实测系统会把链接解析给谁
adb shell cmd package resolve-activity --brief -a android.intent.action.VIEW -d https://example.com/some/path
adb shell am start -W -a android.intent.action.VIEW -d https://example.com/some/path第一条只查询不启动,输出被选中的组件;第二条真正启动并打印 Activity 与耗时。如果第一条返回的是浏览器组件,说明域名归属没建立;如果返回你的 App 但界面仍走浏览器,多半是第 8 步的用户开关。
第 8 步:检查 Android 12+ 的「打开支持的链接」开关
adb shell am start -a android.settings.APPLICATION_DETAILS_SETTINGS -d package:com.example.app在打开的详情页里找「默认打开 / 打开支持的链接 / 添加链接」,确认开关已启用、目标域名已勾选。Android 12 之后这一步是独立于验证的用户授权:验证通过但用户没允许,系统依然把链接交给浏览器。这也是很多人升级系统后突然失效的原因。
第 9 步:排除环境与多用户干扰
adb shell am get-current-user
adb shell pm list users
adb shell cmd package resolve-activity --brief --user 0 -a android.intent.action.VIEW -d https://example.com/x工作资料、分身、多用户各自有独立的链接偏好;国内定制系统还可能把「默认打开」放在不同的菜单层级。若在主用户与工作资料下表现不同,按用户分别检查开关即可。
五、版本差异速查
同一份 APK 在不同 Android 版本上表现可能完全不同,排查时先确认系统版本:
adb shell getprop ro.build.version.release
adb shell getprop ro.build.version.sdk| Android 版本 | API | 验证模型 | 对排查的影响 |
|---|---|---|---|
| 6.0 – 7.x | 23–25 | 首次引入 App Links,安装时一次性验证 | 重装可触发重验 |
| 8.0 – 10 | 26–29 | 验证结果持久化,失败后长期保持 | 需要 verify-app-links 或重装 |
| 11 及以前 | ≤30 | 全有或全无:所有 host 都过才算通过 | 一个域名写错拖垮全部 |
| 12 | 31 | 引入 DomainVerificationManager,按域名独立判定 | 改用 pm get-app-links 读状态 |
| 12+ | ≥31 | 新增用户「打开支持的链接」授权环节 | 验证通过也可能不跳 |
| 13 – 15 | 33–35 | 状态细分更明确,用户选择优先级更高 | 优先查用户开关 |
特别注意 11 与 12 的分界:在 Android 11 上,manifest 里只要有一个 host 的声明文件不可达,整个应用的所有域名都会降级;Android 12 之后改成逐域名判定,所以会出现「主站链接能跳、活动页链接不跳」这种部分生效的情况。别急着下结论说配置错了,先看系统版本。
六、命令速查表
| 目的 | 命令 |
|---|---|
| 读 manifest 里的 autoVerify | apkanalyzer manifest print app.apk | grep -A 12 intent-filter |
| 查包名 | adb shell pm list packages | grep -i example |
| 查声明文件响应头 | curl -sSI https://example.com/.well-known/assetlinks.json |
| 查状态码与重定向 | curl -sS -o /dev/null -w "%{http_code} %{redirect_url}\n" https://example.com/.well-known/assetlinks.json |
| 取 APK 签名指纹 | apksigner verify --print-certs app.apk |
| 取文件里的指纹 | jq -r '.[].target.sha256_cert_fingerprints[]' assetlinks.json |
| 读域名验证状态 | adb shell pm get-app-links com.example.app |
| 重新触发验证 | adb shell pm verify-app-links --re-verify com.example.app |
| 查链接解析结果 | adb shell cmd package resolve-activity --brief -a android.intent.action.VIEW -d https://example.com/x |
| 查旧版域名首选表 | adb shell dumpsys package domain-preferred-apps |
| 打开应用详情页设置 | adb shell am start -a android.settings.APPLICATION_DETAILS_SETTINGS -d package:com.example.app |
七、常见问题(FAQ)
Q1:卸载重装之后链接就能跳了,是不是说明原来装坏了?
不一定。重装会重新触发一次域名验证,如果上次失败只是因为安装时设备离线或省电限制,重装恰好给了它第二次机会。真正修好的是「验证时机」,不是安装包本身。用 pm verify-app-links --re-verify 可以达到同样效果,不用反复卸载。
Q2:选择框里能看到我的 App,但每次都要手选,能设成默认吗?
可以,在应用详情页的「默认打开」里开启。但要清楚这是把普通 Deep Link 设成默认,和 App Link 的自动验证不是一回事:它只对已匹配的链接生效,网站所有权依然没有被校验。
Q3:`assetlinks.json` 返回 200、Content-Type 也对,为什么还是未验证?
按概率排:签名证书指纹不匹配(侧载包最常见)、发生了 301/302 重定向、JSON 里的 package_name 与设备包名不一致、relation 写错、被 robots.txt 屏蔽。用第 3、4 步的命令逐条排除。
Q4:我从第三方站点下载的 APK,链接不跳,是不是下载到修改版了?
不能仅凭这一现象下结论。任何与官网声明证书不同的分发包都会导致验证失败,包括官方的调试版、内测版和旧渠道包。但如果你同时遇到安装时提示签名冲突,那就值得核对来源了,可参考 APK 签名不一致导致安装失败的排查。
Q5:清缓存、清数据、强制停止有没有用?
对 App Links 验证基本没用。验证结果存在系统侧(DomainVerificationManager / 域名首选表),不在应用自己的数据目录里。清应用数据反而会清掉登录态。正确的重来方式是第 6 步的重新触发验证。
Q6:为什么升级到 Android 12 之后突然不跳了?
因为 12 增加了用户授权环节,且验证模型改成按域名独立判定。升级后部分域名需要重新勾选「打开支持的链接」,用 pm get-app-links 看状态、到应用详情页补勾选即可。
Q7:只有 `http://` 链接不跳,`https://` 正常,正常吗?
正常。App Links 要求 https,且 Android 9 起默认禁用明文流量。manifest 里只声明 https scheme 时,http 链接本来就不该匹配。
Q8:我是站长,改完 `assetlinks.json` 要多久生效?
服务端改完立即对新验证请求生效,但设备端有缓存。让用户执行重新触发验证,或者重装应用,通常几秒到几分钟内刷新。不要指望用户自己等它自动恢复。
Q9:这问题能靠换一个 APK 版本解决吗?
只有当你换成与官网声明证书一致的那一份签名时才有用。版本号高低不决定指纹,换版本前先用 apksigner verify --print-certs 比对,能省下大量无效尝试。挑版本前可以先读 targetSdkVersion 说明 理解版本标记的含义,但要注意旧版本的证书可能与现行声明不同。
八、什么时候不是你的设备能修的
把上面九步走完,如果结论落在下面三类,就别在手机上继续折腾了:
- 官网 `assetlinks.json` 本身缺失、重定向或配置错误——只有站点管理员能改;
- 签名证书指纹不匹配(侧载非官方分发包)——需要换成与声明一致的签名,或者接受链接不自动跳转;
- 应用压根没声明 `autoVerify`——这是设计选择,弹选择框属于预期行为。
前两类情况下,可行的替代只有:把链接手动复制进 App、在应用内用自带的打开方式、或在「默认打开」里把它设成普通 Deep Link 的默认处理器。花时间反复重装、换下载源、清数据不会改变服务端的文件和证书。
顺带一提,这个现象和另一些「装完之后的怪事」很容易混淆,但成因完全不同:装完找不到图标属于启动器注册问题,见 装完 APK 桌面无图标排查;点开就闪退属于运行时崩溃,见 APK 装完启动即闪退;安装过程卡住则属于安装会话问题,见 APK 卡在正在安装的会话排查。先分清现象再选文章,能少走很多弯路。
九、延伸阅读
- Android 未知来源安装的现代设置:侧载前先把权限链路理清
- APK 文件结构解析:理解 manifest 与签名块在 APK 里的位置
- APK 卡在正在安装的会话排查:安装阶段失败的另一套机制
- APK 签名不一致导致安装失败:同一证书机制在安装阶段的体现
- targetSdkVersion 说明:理解版本差异对系统行为的影响
- 下载完 APK 找不到文件:分区存储下的定位方法
- 安装后通知不显示:另一类装完之后的权限问题
- 卸载后空间仍然不足:残留文件清理思路
- APK 装完启动即闪退:启动阶段崩溃的 logcat 排查
小结
链接不跳 App 从来不是「没装好」,而是域名归属没建立。按这个顺序定位即可:先用 apkanalyzer 确认 autoVerify 声明,再用 curl 确认 assetlinks.json 可达且无重定向,用 apksigner 比对签名证书指纹,用 pm get-app-links 读系统状态,用 verify-app-links 重触发,最后检查 Android 12+ 的用户开关。九步之内一定能定位到具体是哪一环,而不是靠反复重装碰运气。
对侧载用户来说,最值得记住的一条是:签名证书指纹由分发包决定,不由版本号决定。官网声明的是哪把证书,你手里的 APK 就得是哪把证书签的,否则这条链路在第 5 步就会安静地停下来,不报错、不提示,只是把链接留给浏览器。