Flutter用Auto Route实现Deep Link时跳转浏览器而非应用的问题

Android 端排查与修复 #

1. 验证assetlinks.json 有效性

   • 确保文件放在网站根目录的/.well-known/路径下，能通过https://www.my-host/.well-known/assetlinks.json直接访问，返回200状态码且无重定向。
   • 核对文件内容：package_name必须是应用完整包名，sha256_cert_fingerprints要和当前测试包的签名指纹完全匹配（debug包用debug签名指纹，release包用release指纹，二者不通用）。
   • 执行命令强制触发验证：adb shell am set-debug-app -w com.your.package，重启应用后再测试链接。

2. 修正Intent Filter 配置

   • 确认intent-filter嵌套在MainActivity的标签内，不能放在其他Activity下。
   • 若域名存在带www和不带www的情况，需添加两个<data>标签分别匹配：

     <data android:scheme="https" android:host="www.my-host" android:pathPrefix="/offer/" />
     <data android:scheme="https" android:host="my-host" android:pathPrefix="/offer/" />
     

   • 检查android:autoVerify="true"：所有配置的host必须通过系统验证，否则不会授予应用默认链接处理权，此时会弹出应用选择器（若有浏览器则优先打开）。可通过adb shell dumpsys package domain-preferences查看验证状态。

3. 重置系统域名偏好

   • 若之前测试导致浏览器成为链接默认处理应用，执行命令重置：adb shell pm clear-domain-preferences，之后重新测试链接。

4. 直接测试Deep Link

   • 跳过浏览器，用adb命令直接触发链接，验证应用端配置是否正常：

     adb shell am start -W -a android.intent.action.VIEW -d "https://www.my-host/offer/test" com.your.package
     

iOS 端补充配置（针对双平台问题） #

1. 配置Associated Domains

   • 在Xcode中打开项目，进入Signing & Capabilities，添加Associated Domains，并添加条目：applinks:www.my-host（若有不带www的域名，需额外添加applinks:my-host）。

2. 部署apple-app-site-association 文件

   • 在网站/.well-known/路径下放置该文件，内容示例：

     {
       "applinks": {
         "apps": [],
         "details": [
           {
             "appID": "TEAM_ID.BUNDLE_ID",
             "paths": ["/offer/*"]
           }
         ]
       }
     }
     

   • 确保文件能通过https://www.my-host/.well-known/apple-app-site-association直接访问，无.json后缀，返回200状态码。

3. Info.plist 配置

   • 添加URL Types支持https scheme：

     <key>CFBundleURLTypes</key>
     <array>
       <dict>
         <key>CFBundleURLSchemes</key>
         <array>
           <string>https</string>
         </array>
       </dict>
     </array>
     

Auto Route 配置检查 #

• 确认OfferDetailsRoute已通过AutoRoute注解配置正确的路径，例如：

  @AutoRoute(path: '/offer/:offerId', name: 'OfferDetailsRoute')
  class OfferDetailsScreen extends StatelessWidget { ... }
  

• 在deepLinkBuilder分支中添加日志，确认是否正确捕获到Deep Link路径。

通用测试注意事项 #

• 不要在浏览器地址栏直接输入链接，改用短信、备忘录等应用中的链接点击触发，部分浏览器会直接打开网页而非唤起应用选择器。
• iOS测试需使用真机，模拟器无法正确处理Universal Links。

内容的提问来源于stack exchange，提问作者Amr Mahmoud