Firebase Dynamic Links参数丢失 deepLink获取code为null解决方案

问题复现 #

点击生成的动态链接可正常跳转至App内指定页面，但调用deepLink.queryParameters['code']读取链接携带的code参数时返回null，跳转过程中自定义参数丢失。

测试使用的原始深层链接：

https://.../app?pageName=emailActivationPage&code=7075

原有实现代码：

await Firebase.initializeApp();

  final PendingDynamicLinkData? initialLink =
      await FirebaseDynamicLinks.instance.getInitialLink();

if (widget.initialLink != null) {
      String? code;
      final Uri deepLink = widget.initialLink!.link;
      if (deepLink.queryParameters.containsKey('code')) {
        code = deepLink.queryParameters['code'];
      } else {
        code = 'No code';
      }
      routeCubit.toForgotPasswordPage(code, true);

核心原因 #

• 最常见原因：动态链接拼接不符合规范，自定义参数未正确透传。手动拼接Firebase动态链接时，没有将带参数的完整深层链接做URL编码后放到link参数位，而是直接把自定义参数拼在动态链接域名后，Firebase服务端解析时会将未编码的code等参数识别为动态链接自身的配置参数，不会透传到App内拿到的deepLink对象中。
• 转义错误：拼接链接时未对特殊字符做转义，比如&符号未被编码，导致参数被截断拆分。
• 控制台规则冲突：Firebase动态链接控制台配置的路径重写规则存在截断逻辑，匹配到对应路径时自动丢弃了query参数。
• 监听场景遗漏：原有代码只处理了冷启动时的getInitialLink()，未覆盖App在后台时被链接唤起的场景，且通过widget.initialLink传值的链路存在对象丢失风险。

修复配置步骤 #

1. 按规范生成动态链接
   所有自定义深层链接必须做完整URL编码，作为link参数的值拼接到Firebase动态链接中，不要直接把自定义参数放在动态链接域名根路径后。正确的链接结构参考：

   https://你的动态链接域名/?link=编码后的完整深层链接&apn=安卓应用包名&ibi=iOS应用包名&isi=iOS应用ID
   

   对应本次测试链接的正确拼接效果为：

   https://你的动态链接域名/?link=https%3A%2F%2F你的应用关联域名%2Fapp%3FpageName%3DemailActivationPage%26code%3D7075&apn=你的安卓包名&ibi=你的iOS包名
   

   其中https://.../app?pageName=emailActivationPage&code=7075整体编码后作为link参数值，和Firebase要求的应用标识参数分层放置。
2. 检查控制台配置
   进入Firebase控制台动态链接配置页，检查使用的链接前缀是否配置了强制重定向、路径重写规则，移除会截断query参数的自定义规则，确保深层链接可以完整透传。
3. 补全全场景监听逻辑
   统一处理冷启动、后台唤起两种场景的动态链接回调，拿到链接对象后先打印全量链接地址做调试，避免上层传值过程中丢失链接信息。

参考实现代码 #

await Firebase.initializeApp();

// 处理冷启动唤起场景
final PendingDynamicLinkData? initialLink =
    await FirebaseDynamicLinks.instance.getInitialLink();
handleDeepLinkNavigate(initialLink);

// 处理应用驻留后台时的链接唤起场景
FirebaseDynamicLinks.instance.onLink.listen((linkData) {
  handleDeepLinkNavigate(linkData);
});

// 统一封装跳转逻辑
void handleDeepLinkNavigate(PendingDynamicLinkData? linkData) {
  if (linkData == null) return;
  final Uri deepLink = linkData.link;
  // 调试阶段打印完整链接，确认参数位置
  debugPrint('接收到的完整深层链接: $deepLink');
  final String? code = deepLink.queryParameters['code'];
  routeCubit.toForgotPasswordPage(code ?? 'No code', true);
}

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