Flutter Unity Widget 在 Android 上的 BufferQueue 问题分析与解决方案

问题背景

在使用 Flutter Unity Widget 插件进行 Flutter 与 Unity 集成开发时，Android 平台上可能会出现一个常见的错误："BufferQueue has been abandoned"。这个错误会导致 Unity 视图无法正常显示，同时控制台会不断重复输出错误信息。

错误表现

开发者在使用 Flutter Unity Widget 时，可能会遇到以下典型症状：

1. 应用界面只显示背景色（如示例中的黄色），Unity 内容无法显示
2. Android 日志中不断重复输出错误信息："E/BufferQueueProducer: [ImageReader] dequeueBuffer: BufferQueue has been abandoned"
3. 应用不会崩溃，但 Unity 内容完全不可见

根本原因

这个问题主要与 Flutter 引擎版本有关，具体来说是 Flutter 3.19.x 版本中存在的一个已知 bug。该 bug 影响了 Flutter 与原生视图的交互方式，特别是在处理 Surface 和 BufferQueue 时出现了问题。

解决方案

根据不同的 Flutter 版本，有以下几种解决方案：

方案一：升级 Flutter 版本

1. 升级到 Flutter 3.22 或更高版本，该版本已经修复了这个 bug
2. 如果升级到 Flutter 3.24，还需要应用额外的补丁（具体修改可参考相关 commit）

方案二：使用 workaround 参数（适用于必须使用 Flutter 3.19 的情况）

在 UnityWidget 组件中添加以下参数：

UnityWidget(
  onUnityCreated: onUnityCreated,
  useAndroidViewSurface: true,  // 关键参数
)

这个参数会改变 Flutter 的嵌入模式，使用不受此 bug 影响的替代方案。

其他建议配置

1. Unity 版本选择：建议使用 Unity 2022.3.x 版本，这是经过验证的稳定版本
2. 图形 API 设置：在 Unity 中，将 Graphics API 设置为 OpenGLES3，这可以避免一些 Android 上的冻结和崩溃问题
3. Android 配置：确保 Android 项目的 minSdkVersion 至少为 24，targetSdkVersion 设置为 33

实现示例

以下是经过验证可用的基本实现代码：

import 'package:flutter/material.dart';
import 'package:flutter_unity_widget/flutter_unity_widget.dart';

class UnityDemoScreen extends StatefulWidget {
  const UnityDemoScreen({super.key});

  @override
  State<UnityDemoScreen> createState() => _UnityDemoScreenState();
}

class _UnityDemoScreenState extends State<UnityDemoScreen> {
  UnityWidgetController? _unityWidgetController;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: UnityWidget(
          onUnityCreated: onUnityCreated,
          useAndroidViewSurface: true, // 关键解决方案
        ),
      ),
    );
  }

  void onUnityCreated(controller) {
    _unityWidgetController = controller;
  }
}

总结

Flutter Unity Widget 在 Android 平台上的 BufferQueue 问题主要是由 Flutter 引擎版本引起。开发者可以通过升级 Flutter 版本或使用 useAndroidViewSurface 参数来解决这个问题。同时，选择合适的 Unity 版本和正确的图形 API 设置也是确保集成成功的关键因素。