iOS发布模式下冷启动时FirebaseDynamicLinks.getInitialLink始终返回null

检查iOS基础配置完整性 #

• 确认Associated Domains已添加，格式为applinks:<你的动态链接域名>，需与Firebase控制台动态链接设置中的域名完全匹配。
• 检查Info.plist是否添加FirebaseDynamicLinksCustomDomains字段，值为包含动态链接域名的数组（例如["https://your.page.link"]）。
• 确保GoogleService-Info.plist是从Firebase控制台下载的最新版本，且已正确关联到iOS项目的主目标。

调整getInitialLink的调用时机 #

当前在HomePage的initState中调用初始化逻辑，可能Firebase尚未完成初始化。建议将动态链接初始化移至runApp之后，或通过WidgetsBinding.instance.addPostFrameCallback延迟执行：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  runApp(const MyApp());

  WidgetsBinding.instance.addPostFrameCallback((_) {
    initDynamicLink();
  });
}

验证动态链接生成参数 #

生成动态链接时需确保iOS相关参数配置正确：

• 必须指定iOSBundleId，且与应用的Bundle ID完全一致。
• 使用自定义域名时，需确认域名已在Firebase控制台完成验证。

排查发布模式特殊限制 #

• 若开启了代码混淆（R8/ProGuard），需添加Firebase Dynamic Links的混淆规则：

  -keep class com.google.firebase.dynamiclinks.** { *; }
  

• 关闭iOSBuild Settings中的Enable Bitcode选项，部分版本的Firebase插件对Bitcode支持存在兼容性问题。

替代方案：通过生命周期回调处理 #

如果getInitialLink仍无效，可监听应用生命周期的resumed状态，重新获取并处理链接：

void initDynamicLink() {
  // 后台唤醒时的链接处理
  FirebaseDynamicLinks.instance.onLink.listen((pendingLink) {
    handleDeepLink(pendingLink.link);
  });

  // 监听应用恢复状态
  WidgetsBinding.instance.addObserver(_LifecycleObserver(
    onResume: () async {
      final linkData = await FirebaseDynamicLinks.instance.getInitialLink();
      if (linkData?.link != null) {
        handleDeepLink(linkData!.link);
        // 处理后清除pending链接，避免重复触发
        await FirebaseDynamicLinks.instance.clearPendingDynamicLinkData();
      }
    },
  ));
}

void handleDeepLink(Uri deepLink) {
  Sentry.captureMessage("deepLink: $deepLink");
  ref.read(goRouterProvider).push(deepLink.path);
}

class _LifecycleObserver extends WidgetsBindingObserver {
  final VoidCallback? onResume;

  _LifecycleObserver({this.onResume});

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.resumed) {
      onResume?.call();
    }
  }
}

内容的提问来源于stack exchange，提问作者1ManStartup