Flutter配置App Linking/Deep Linking无效问题求助

开发者阿泽

2026-7-10

排查与解决步骤

1. 校验AndroidManifest.xml的Intent-Filter配置

确保你的intent-filter完全匹配目标URL，正确配置示例如下：

<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" />
    <!-- 匹配你的HTTPS根链接 -->
    <data
        android:scheme="https"
        android:host="api.area.baptiste.zip"
        android:path="/" /> <!-- 若需匹配所有子路径，改用pathPrefix="/" -->
</intent-filter>

注意点：

android:autoVerify="true"是开启App Links的必要配置，需与assetlinks.json配合生效
确认该intent-filter嵌套在主Activity的标签内
path或pathPrefix需精准匹配目标链接路径

2. 修正adb测试命令

使用精准的adb命令直接测试Intent唤起，替换命令中的包名为你的Flutter App包名（可在android/app/build.gradle的applicationId字段找到）：

adb shell am start -a android.intent.action.VIEW -d "https://api.area.baptiste.zip" com.your.package.name

若命令执行后App能正常打开，说明Intent配置无问题，问题出在浏览器侧或App Links验证环节
若仍无响应，直接定位到Intent配置错误，重新检查AndroidManifest内容

3. 确认App Links验证状态

即使通过Google工具验证了assetlinks.json，仍需确保手机端验证通过：

卸载现有App后重新安装（系统会在安装时自动校验assetlinks.json）
进入手机设置 -> 应用 -> 你的App -> 打开方式，查看是否存在默认打开链接选项，无此选项则说明验证未通过
核对assetlinks.json的target字段：package_name需与App包名完全一致，sha256_cert_fingerprints需匹配当前测试包的签名指纹（debug包和release包的签名指纹不同，需对应配置）

4. 优化NestJS根路由体验（非唤起核心，但提升用户感知）

Deeplink唤起本身不依赖Web服务器路由，但为避免用户看到404页面，可在NestJS添加根路由返回引导页面：

@Get()
root() {
  return `
    <html>
      <body>
        <p>请打开App继续操作</p>
        <script>
          // 尝试唤起App，超时后引导下载
          window.location.href = "yourapp://api.area.baptiste.zip";
          setTimeout(() => {
            window.location.href = "你的App下载链接";
          }, 2000);
        </script>
      </body>
    </html>
  `;
}

5. 验证uni_links初始化逻辑

确保Flutter端正确监听链接事件：

import 'package:uni_links/uni_links.dart';

void initUniLinks() async {
  // 处理冷启动时的链接
  final initialLink = await getInitialLink();
  if (initialLink != null) {
    handleLink(initialLink);
  }

  // 监听热启动时的链接
  linkStream.listen((String? link) {
    if (link != null) {
      handleLink(link);
    }
  });
}

void handleLink(String link) {
  // 在这里实现你的业务逻辑，比如跳转指定页面
  print('收到链接: $link');
}

在main()函数中调用initUniLinks()（注意异步处理）。

6. 核对签名指纹

使用以下命令获取签名指纹，确保与assetlinks.json中的值一致：

# 获取debug包签名指纹
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# 获取release包签名指纹
keytool -list -v -keystore 你的-release-keystore.jks -alias 你的别名

内容的提问来源于stack exchange，提问作者Baptiste LEROYER

Flutter配置App Linking/Deep Linking无效问题求助

1. 校验AndroidManifest.xml的Intent-Filter配置 #

2. 修正adb测试命令 #

3. 确认App Links验证状态 #

4. 优化NestJS根路由体验（非唤起核心，但提升用户感知） #

5. 验证uni_links初始化逻辑 #