Flutter 3.27 推送冷启动黑屏:深链接冲突记录

记录华为设备推送拉起时的 URI 报错,以及深链接默认开关变化的处理。

适用版本

原环境为 Flutter 3.27、jpush_flutter 3.1.6+、GetX 4.6.6 与鸿蒙 4.2.0。

本文目录
  1. 当时的环境与错误
  2. Flutter 3.27 的默认开关变化
  3. Android 配置位置
  4. iOS 与处理范围
  5. 可复用的排查顺序
  6. 参考

2025 年 1 月的项目记录中,从应用图标启动一切正常,华为设备通过通知冷启动却出现黑屏;应用已经存活时,点击通知回到前台正常。这个差异把排查范围缩到了冷启动路由与通知载荷。

当时的环境与错误

text
Flutter 3.27.0 及之后的当时版本
jpush_flutter 3.1.6 及以上的当时版本
GetX 4.6.6
华为鸿蒙 4.2.0

主要报错是 URI 解析失败:

text
FormatException: Scheme not starting with alphabetic character

调试过程还出现过 Navigator 的 GlobalKey 重复错误。这些是原项目的现象,不是所有推送黑屏的统一原因。

原项目:推送冷启动时的路由错误

Flutter 3.27 的默认开关变化

Flutter 官方的 breaking change 文档说明,深链接开关从默认关闭变为默认开启,稳定版变化发生在 3.27。使用第三方深链接处理的应用,需要明确由哪一套机制消费外部链接。

原项目中,通知拉起时的字段进入深链接与路由解析,随后触发异常。处理方式是停用 Flutter 默认深链接入口,让项目自己的通知和路由逻辑接管。

Android 配置位置

在 android/app/src/main/AndroidManifest.xml 中,把 metadata 放在承载 Flutter 的 Activity 内。原文章仅描述放在 application 中,层级不够准确。

xml
<application ...>
    <activity
        android:name=".MainActivity"
        ...>
        <meta-data
            android:name="flutter_deeplinking_enabled"
            android:value="false" />
    </activity>
</application>

这是展示配置层级的片段,省略号代表工程已有属性。保留原 Activity 的其他声明。

iOS 与处理范围

iOS 使用第三方深链接处理时,对应的 Info.plist 配置是:

xml
<key>FlutterDeepLinkingEnabled</key>
<false/>

关闭的是 Flutter 默认深链接处理,项目若依赖它处理应用链接,必须先明确替代路径。应用本身需要的深链接能力不能只为消除报错而丢失。Android 的故障也不能据此推定 iOS 存在同样问题。

可复用的排查顺序

区分图标启动、通知冷启动与通知热启动;对照第一条异常和进入导航器的原始路由字段;确认框架版本是否改变默认行为。修复针对 URI 消费与导航过程,不能靠吞掉 FormatException 或反复创建 Navigator 掩盖。

参考

作者:NeverOuO。原载 NeverOuO 个人小站,现收录于云屿来文章与教程。

返回全部文章

把好用的工具分享给朋友

分享

发送链接,让朋友直接打开这个页面。

访问统计

我们统计页面浏览、渠道来源、产品入口点击与分享次数,用于了解产品如何被发现。这项统计不使用用户标识、Cookie 或跨站追踪,也不读取上传文件或表单内容。