原环境为 Flutter 3.27、jpush_flutter 3.1.6+、GetX 4.6.6 与鸿蒙 4.2.0。
2025 年 1 月的项目记录中,从应用图标启动一切正常,华为设备通过通知冷启动却出现黑屏;应用已经存活时,点击通知回到前台正常。这个差异把排查范围缩到了冷启动路由与通知载荷。
当时的环境与错误
Flutter 3.27.0 及之后的当时版本
jpush_flutter 3.1.6 及以上的当时版本
GetX 4.6.6
华为鸿蒙 4.2.0
主要报错是 URI 解析失败:
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 中,层级不够准确。
<application ...>
<activity
android:name=".MainActivity"
...>
<meta-data
android:name="flutter_deeplinking_enabled"
android:value="false" />
</activity>
</application>
这是展示配置层级的片段,省略号代表工程已有属性。保留原 Activity 的其他声明。
iOS 与处理范围
iOS 使用第三方深链接处理时,对应的 Info.plist 配置是:
<key>FlutterDeepLinkingEnabled</key>
<false/>
关闭的是 Flutter 默认深链接处理,项目若依赖它处理应用链接,必须先明确替代路径。应用本身需要的深链接能力不能只为消除报错而丢失。Android 的故障也不能据此推定 iOS 存在同样问题。
可复用的排查顺序
区分图标启动、通知冷启动与通知热启动;对照第一条异常和进入导航器的原始路由字段;确认框架版本是否改变默认行为。修复针对 URI 消费与导航过程,不能靠吞掉 FormatException 或反复创建 Navigator 掩盖。


