Android Studio 运行 Flutter iOS 真机白屏，但 Xcode 和命令行正常的排查记录

最近在调试一个 Flutter 项目时遇到一个比较迷惑的问题：

同一台 iOS 26 真机，同一个 Flutter 工程：

用 Xcode 运行，正常
用命令行 flutter run，正常
用 Android Studio 点运行，安装成功，但启动后白屏

一开始很容易怀疑是 iOS 26 兼容性、Flutter 版本、Pods、缓存或者原生启动代码的问题。但最后发现，根因其实是 Android Studio Flutter 插件默认带上的一个启动参数：--start-paused。

问题现象

环境大概是：

Flutter 3.47.1
Xcode 26.6
iOS 26 真机
Android Studio + Flutter 插件

Android Studio 运行后，App 会成功安装到 iPhone 上，也能启动，但界面一直白屏。

同样的项目，用 Xcode 跑正常；用命令行直接跑也正常：

bash 复制代码

/Users/mt/Desktop/zhiboyi/dev/.fvm/flutter_sdk/bin/flutter run \
  --device-id=00008130-001E5D382461401C \
  lib/main.dart

这说明项目本身、iOS 工程配置、Pods、签名、设备连接，大概率都不是根因。

关键线索

查看 Android Studio 日志后，发现它实际执行的命令类似这样：

css 复制代码

/Users/mt/Desktop/zhiboyi/dev/.fvm/flutter_sdk/bin/flutter \
  --no-color run \
  --machine \
  --track-widget-creation \
  --device-id=00008130-001E5D382461401C \
  --start-paused \
  --dart-define=flutter.inspector.structuredErrors=true \
  --devtools-server-address=http://127.0.0.1:9100 \
  lib/main.dart

重点是这个参数：

css 复制代码

--start-paused

Android Studio 为了接入 Debugger，会让 Flutter 以暂停模式启动。也就是说 Dart isolate 启动后会先暂停，等 IDE 的 debugger 连接并发送 resume。

如果这个 resume 没有成功，Flutter 首帧就不会正常绘制，表现出来就是 App 已经打开，但一直白屏。

复现方式

为了确认问题是不是 Android Studio 本身导致的，可以直接在命令行加上同样的参数：

bash 复制代码

/Users/mt/Desktop/zhiboyi/dev/.fvm/flutter_sdk/bin/flutter run \
  --device-id=00008130-001E5D382461401C \
  --start-paused \
  lib/main.dart

结果命令行也复现了白屏。

到这里就基本可以确定：

问题不是 Android Studio 缓存，也不是项目代码，而是 --start-paused 这条 Flutter debug 启动路径在当前 iOS 真机环境下没有正确 resume。

解决方案

在 Android Studio 的 Flutter Run Configuration 里，找到：

arduino 复制代码

Additional run args

加上：

css 复制代码

--no-start-paused

然后重新运行。

最终 Android Studio 仍然可以正常安装和启动 App，但不会让 Dart isolate 一开始暂停，白屏问题解决。

为什么 Xcode 没问题？

因为 Xcode 运行 Flutter iOS 工程时，走的是 Xcode scheme 和 iOS 原生启动流程，不会像 Android Studio Flutter 插件那样自动附加 --start-paused。

普通命令行 flutter run 默认也不会带这个参数，所以也正常。

真正有问题的是这种启动方式：

arduino 复制代码

flutter run --start-paused

它依赖 debugger attach 后恢复 isolate。一旦这个过程在 iOS 26 真机上失败或不稳定，就会出现白屏。

排查建议

如果你也遇到类似问题，可以按这个顺序排查：

先确认命令行不带 --start-paused 是否正常。
再用命令行手动加 --start-paused 复现。
如果加了就白屏，基本可以确认是 debug attach/resume 问题。
在 Android Studio 的 Additional run args 中加入：

css 复制代码

--no-start-paused

如果需要稳定调试，也可以临时使用命令行运行，或者用 Xcode/Flutter DevTools 组合排查日志。

总结

这次问题的关键不在 iOS 页面代码，也不在 Flutter 首屏逻辑，而在启动参数。

Android Studio Flutter 插件默认会用类似下面的方式运行 debug：

css 复制代码

flutter run --machine --start-paused ...

在某些 iOS 26 真机环境下，--start-paused 会导致 isolate 没有被恢复，App 停在首帧之前，看起来就是白屏。

最终解决方式很简单：

arduino 复制代码

Additional run args: --no-start-paused

如果你的 Flutter iOS 真机调试也出现"Android Studio 白屏，但 Xcode 和命令行正常"，可以优先检查 Android Studio 实际执行的 Flutter run 参数。