如何将带有flutter_storybook的复杂Flutter应用作为模块接入原生Kotlin应用？

1. 入口函数执行逻辑异常 #

• 检查main.dart的main()函数是否包含仅适配独立Flutter应用的初始化逻辑：比如独立运行时需要的权限申请、全局配置读取、第三方SDK初始化依赖了原生层单独提供的参数，模块集成场景下这些参数缺失会导致main函数阻塞，无法触发runApp()
• 如果你的main函数使用了async修饰，要确保WidgetsFlutterBinding.ensureInitialized()是第一行执行的代码，正确写法示例：

void main() async {
  // 必须第一行调用初始化
  WidgetsFlutterBinding.ensureInitialized();
  // 后续异步逻辑
  await initSDK();
  runApp(const MyApp());
}

2. flutter_storybook 入口冲突 #

• 确认你配置的入口文件没有默认走storybook的入口：很多集成flutter_storybook的项目会在main.dart里加分支判断，比如根据编译参数决定走正常App还是走storybook，模块集成时如果没传入对应的编译参数，可能会走空逻辑或者storybook的渲染逻辑，没有渲染正常的App页面
• 可以单独写一个main_module.dart作为集成到原生时的专用入口，剥离storybook相关的逻辑，然后在原生层配置这个入口：
  Kotlin层配置指定入口示例：

val flutterIntent = FlutterActivity
  .withCachedEngine("my_engine_id")
  .dartEntrypoint("main_module") // 指定自定义的入口函数名
  .build(this)
startActivity(flutterIntent)

3. Flutter引擎初始化配置错误 #

• 不要使用每次启动Activity都新建引擎的模式：每次新建引擎会有1-2秒的黑屏期，官方推荐提前初始化缓存引擎，在Application的onCreate里提前初始化好引擎实例：

class MyApplication : Application() {
  lateinit var flutterEngine: FlutterEngine
  override fun onCreate() {
    super.onCreate()
    flutterEngine = FlutterEngine(this)
    // 提前执行dart入口代码
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )
    // 缓存引擎
    FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)
  }
}

• 检查是否开启了渲染加速配置：在AndroidManifest.xml的FlutterActivity节点添加硬件加速配置：

<activity
  android:name="io.flutter.embedding.android.FlutterActivity"
  android:hardwareAccelerated="true" />

4. 资源路径适配问题 #

• 模块集成场景下Flutter的资源路径会发生变化，如果你在代码里写死了资源路径的绝对路径，会导致资源加载失败，页面空白被误判为黑屏，所有资源引用都要使用相对路径，示例：

Image.asset("images/icon.png") // 正确，不要加开头的/assets/前缀

5. 调试排查方法 #

• 连接Android Studio的Flutter调试工具，观察启动时的控制台日志，是否有报错信息抛出
• 给main函数加逐行日志打印，确认是否执行到了runApp()方法，如果没执行到就是之前的逻辑阻塞了，如果执行到了还是黑屏，就是页面渲染逻辑的问题

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