Android 深度链接与 App Links：从 URI Scheme 到可验证的应用跳转
深度链接（Deep Link）是移动端产品常见的诉求：从网页、通知、分享卡片里点一个链接，直接打开 App 内的某个页面。但实现方式不止一种，不同方案的安全性和用户体验差异很大。本文从最基础的 URI Scheme 讲起，逐步过渡到 Android App Links 的完整实现与常见踩坑。
一、URI Scheme：最简单，也最脆弱
最早的做法是在 AndroidManifest.xml 里给 Activity 注册一个自定义 scheme：
<activity android:name=".DeepLinkActivity">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="myapp" android:host="detail" />
</intent-filter>
</activity>
这样 myapp://detail?id=123 就能拉起 App。
问题： 任何 App 都可以声明相同的 scheme。用户点击链接时，系统会弹出选择框；恶意 App 也可以劫持这个链接，造成安全隐患。对于支付、登录回调等敏感场景，URI Scheme 基本不可用。
二、App Links：基于域名验证的可信跳转
Android 6.0（API 23）引入了 App Links，核心思路是：
让 App 证明自己拥有某个域名，系统验证通过后，这个域名的 HTTP/HTTPS 链接就只会打开你的 App，不再弹选择框。
2.1 Manifest 配置
<activity android:name=".DeepLinkActivity">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="https"
android:host="example.com"
android:pathPrefix="/detail" />
</intent-filter>
</activity>
关键点：
android:autoVerify="true"告诉系统在 App 安装时自动验证域名归属scheme必须是https（或http，但强烈推荐 https）- 可以配置多个
<data>标签，支持多路径
2.2 Digital Asset Links 文件
在你的服务器上放一个 JSON 文件，路径固定为：
https://example.com/.well-known/assetlinks.json
内容如下：
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.myapp",
"sha256_cert_fingerprints": [
"AA:BB:CC:DD:EE:FF:..."
]
}
}
]
获取签名指纹：
# debug keystore
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
# release keystore
keytool -list -v -keystore /path/to/release.keystore
从输出中找 SHA256: 那行，格式化成冒号分隔的大写形式即可。
2.3 验证流程
App 安装后，系统会异步请求 assetlinks.json，对比包名和签名。验证成功后：
- 对应域名的 https 链接会直接打开 App，不弹选择框
- 验证失败时降级为普通 Intent，仍会弹选择框或打开浏览器
三、接收并解析深度链接
在目标 Activity 里：
class DeepLinkActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
handleIntent(intent)
}
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
handleIntent(intent)
}
private fun handleIntent(intent: Intent) {
val uri: Uri? = intent.data
if (uri == null) {
// 正常启动，不是深度链接
navigateToHome()
return
}
val path = uri.path ?: ""
val id = uri.getQueryParameter("id")
when {
path.startsWith("/detail") && id != null -> {
navigateToDetail(id)
}
path.startsWith("/profile") -> {
val userId = uri.lastPathSegment
navigateToProfile(userId)
}
else -> navigateToHome()
}
finish() // DeepLinkActivity 只做路由，导航完就关掉
}
}
注意 onNewIntent：当 Activity 以 singleTop 或 singleTask 启动模式运行时，重复点击同一链接不会重建 Activity，而是走 onNewIntent，务必处理。
四、与 Navigation Component 集成
如果项目用了 Jetpack Navigation，可以直接在 nav_graph.xml 里配置 deep link：
<fragment
android:id="@+id/detailFragment"
android:name="com.example.DetailFragment">
<argument
android:name="itemId"
app:argType="string" />
<deepLink
app:uri="https://example.com/detail/{itemId}" />
</fragment>
然后在 AndroidManifest.xml 里用 <nav-graph> 自动生成 intent-filter：
<activity android:name=".MainActivity">
<nav-graph android:value="@navigation/nav_graph" />
</activity>
Navigation 会自动解析 URI 参数，直接填充到 navArgs 里，省去手动解析的代码。
五、常见踩坑
5.1 验证一直不通过
- 文件路径问题：
.well-known/目录在很多 Web 服务器上默认不返回隐藏目录，检查 Nginx/Apache 配置 - Content-Type： 必须是
application/json，不能是text/plain - 重定向：
assetlinks.json不能有 HTTP 重定向，系统不会跟随 - 多签名： debug 和 release 的签名不同，开发阶段建议把两个指纹都加进去
验证工具：
# 在线验证
https://developers.google.com/digital-asset-links/tools/generator
# adb 强制重新验证（需要重新安装或清除验证缓存）
adb shell pm get-app-links --package com.example.myapp
5.2 Android 12 的变化
Android 12（API 31）收紧了未验证链接的处理：
- 如果 App Links 验证失败，链接不再默认打开 App，而是直接在浏览器中打开
- 同时引入了新的 API：
DomainVerificationManager，可以查询验证状态
val manager = getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(packageName)
val unverified = userState?.hostToStateMap
?.filter { it.value == DomainVerificationUserState.DOMAIN_STATE_NONE }
?.keys
// 未验证的域名列表
5.3 LaunchMode 与返回栈
深度链接打开的 Activity 默认会被加入当前返回栈。如果想让深度链接打开一个全新的任务栈：
<activity
android:name=".DeepLinkActivity"
android:launchMode="singleTask"
android:taskAffinity="" />
或在 Intent Flag 里处理：
intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
5.4 测试深度链接
# 测试 URI Scheme
adb shell am start -W -a android.intent.action.VIEW \
-d "myapp://detail?id=123" com.example.myapp
# 测试 App Links（https）
adb shell am start -W -a android.intent.action.VIEW \
-d "https://example.com/detail?id=456" com.example.myapp
六、多域名与子路径策略
实际项目中往往有多个域名（生产、测试、国际化）需要处理：
<!-- 同一个 intent-filter 只能写一个 host -->
<intent-filter android:autoVerify="true">
<data android:scheme="https" android:host="example.com" />
</intent-filter>
<intent-filter android:autoVerify="true">
<data android:scheme="https" android:host="www.example.com" />
</intent-filter>
<intent-filter android:autoVerify="true">
<data android:scheme="https" android:host="m.example.com" />
</intent-filter>
每个域名都需要单独放 assetlinks.json，或者用 include 指向同一个文件。Digital Asset Links 支持通过 include 复用：
[{
"include": "https://primary.example.com/.well-known/assetlinks.json"
}]
小结
| 方案 | 安全性 | 用户体验 | 适用场景 |
|---|---|---|---|
| URI Scheme | 低（可被劫持） | 可能弹选择框 | 内部跳转、无安全需求 |
| App Links（已验证） | 高（域名绑定） | 直接打开，无弹框 | 分享、通知、支付回调 |
| App Links（未验证） | 低 | 降级到浏览器 | — |
关键结论：
- 对外链接（分享、推广、邮件）优先用 App Links，完成域名验证
assetlinks.json要在 CI/CD 里维护，发布新签名时同步更新指纹- Android 12+ 验证失败的代价更重，上线前务必用
adb shell pm get-app-links确认状态 - Navigation Component 的
<deepLink>是减少样板代码的好方式，但要注意参数类型安全
