Capacitor v6 中 Android 自定义 URL 方案拦截失效问题解析

问题背景

在移动应用开发中，深度链接（Deep Linking）是实现应用间跳转和网页与应用交互的重要技术。Capacitor 作为跨平台开发框架，在 v6.1.2 版本中出现了 Android 平台上自定义 URL 方案（Custom URL Scheme）无法被正确拦截的问题。

现象描述

开发者在配置 Android 应用时同时使用了两种深度链接方式：

1. 标准的 Android App Links（基于 HTTPS 方案）
2. 自定义 URL 方案（如 myapp://）

虽然 HTTPS 方案的深度链接工作正常，但自定义 URL 方案却无法被应用拦截处理。开发者尝试了两种配置方式：

• 通过 strings.xml 定义方案名称
• 直接在 AndroidManifest.xml 中硬编码方案名称

但两种方式均未能解决问题。

问题根源

经过深入排查，发现问题出在 AndroidManifest.xml 文件的 intent-filter 配置上。Capacitor 默认会在主 intent-filter 中添加 android:autoVerify="true" 属性，这是用于验证 Android App Links 的标准配置。

关键点在于：

1. 当 autoVerify 属性存在时，该 intent-filter 专用于处理 HTTPS 方案的深度链接
2. 自定义 URL 方案需要单独配置在没有 autoVerify 属性的 intent-filter 中
3. 两种方案不能混用同一个 intent-filter

解决方案

正确的配置方式是将两种深度链接方案分开定义：

<!-- 处理 HTTPS 方案的 App Links -->
<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="yourdomain.com" />
</intent-filter>

<!-- 处理自定义 URL 方案 -->
<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" />
</intent-filter>

技术要点

1. autoVerify 属性：这是 Android 6.0 引入的特性，用于自动验证应用是否拥有指定域名的所有权。它只适用于 HTTPS 方案。

2. intent-filter 分离：Android 系统对不同类型的深度链接处理机制不同，必须分开配置才能确保所有方案都能被正确处理。

3. 兼容性考虑：这种配置方式在 Capacitor v5 中可能不是必须的，但在 v6 中由于框架默认添加了 autoVerify 属性，开发者需要特别注意。

最佳实践建议

1. 始终为不同类型的深度链接使用单独的 intent-filter
2. 自定义 URL 方案应避免使用常见的前缀（如 http、https 等）
3. 测试时使用 adb 命令模拟深度链接调用：adb shell am start -W -a android.intent.action.VIEW -d "myapp://path" your.package.name
4. 考虑在应用启动时添加日志，检查收到的 Intent 数据

总结

Capacitor v6 对 Android 深度链接的处理方式有所变化，开发者需要理解 Android 系统对不同类型的深度链接的处理机制。通过正确分离 intent-filter 配置，可以确保应用同时支持标准的 Android App Links 和自定义 URL 方案。这个问题也提醒我们，在框架升级时需要仔细检查平台特定的配置变化。