实战 Flutter 嵌入 Unity：解决混合开发中的通信与构建难题

30 July 2025

Update: 14 January 2026

在生产环境中，单一技术栈往往难以兼顾极致的UI开发效率与顶级的3D渲染能力。我们经常面临这样的抉择：是用 Flutter 快速构建现代化的跨平台界面，还是用 Unity 打造沉浸式的3D体验？为什么不两者兼得？ 将 Flutter 作为应用的“骨架”处理复杂的业务逻辑与2D交互，同时将 Unity 作为一个“高能组件”嵌入其中处理3D模型与AR场景，是目前混合开发中最具性价比的架构方案。但这条路充满了构建失败、内存泄漏和通信延迟的“坑”。本文将分享我们在生产项目中稳定集成 Flutter 与 Unity 的实战经验。

架构设计：双向通信的核心逻辑

集成的核心不仅仅是将 Unity 的视图层级叠加在 Flutter 之上，更关键的是解决双向通信（Bi-directional Communication）。我们需要在 Dart（Flutter）与 C#（Unity）之间建立一条高效的消息总线。在我们的方案中，使用了社区维护的 flutter_unity_widget 作为桥梁。

架构提示： 不要尝试在 Unity 中处理复杂的 REST API 请求或业务状态管理。让 Flutter 负责数据获取，并通过 JSON 消息将最终状态传递给 Unity 进行渲染。

代码实战：建立通信桥梁

首先，我们需要在 Unity 端创建一个消息接收器。这个脚本必须挂载在场景中一个始终激活的 GameObject 上。以下是处理 JSON 消息的 C# 实现：

1. Unity 端 (C#)

using System;
using UnityEngine;
using Newtonsoft.Json.Linq; // 推荐使用 Newtonsoft 处理 JSON

public class FlutterMessageManager : MonoBehaviour
{
    // 确保这个方法名与 Flutter 端调用的一致
    public void MessageFromFlutter(string message)
    {
        try 
        {
            JObject json = JObject.Parse(message);
            string action = (string)json["action"];
            
            // 根据 action 分发逻辑
            switch (action)
            {
                case "rotate_model":
                    float angle = (float)json["data"]["angle"];
                    RotateModel(angle);
                    break;
                default:
                    Debug.LogWarning("Unknown action: " + action);
                    break;
            }
        }
        catch (Exception e)
        {
            Debug.LogError("Failed to parse message: " + e.Message);
        }
    }

    private void RotateModel(float angle)
    {
        // 具体的 3D 逻辑
        transform.Rotate(0, angle, 0);
        
        // 反馈给 Flutter
        UnityMessageManager.Instance.SendMessageToFlutter("RotationComplete");
    }
}

2. Flutter 端 (Dart)

在 Flutter 侧，我们需要嵌入 UnityWidget 并管理其生命周期。最常见的错误是未正确处理 Controller 的销毁，导致应用在页面切换时崩溃。

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

class UnityViewPage extends StatefulWidget {
  @override
  _UnityViewPageState createState() => _UnityViewPageState();
}

class _UnityViewPageState extends State<UnityViewPage> {
  UnityWidgetController? _unityWidgetController;

  @override
  void dispose() {
    // 务必释放 Controller，防止内存泄漏
    _unityWidgetController?.dispose();
    super.dispose();
  }

  void _onUnityCreated(controller) {
    _unityWidgetController = controller;
  }

  void _onUnityMessage(message) {
    print('Received from Unity: $message');
  }

  void _rotateModel() {
    if (_unityWidgetController != null) {
      // 构建 JSON 消息
      var message = jsonEncode({
        "action": "rotate_model",
        "data": {
          "angle": 45.0
        }
      });
      
      // 发送给 Unity 中挂载了 FlutterMessageManager 的对象
      // 参数: GameObject 名称, 方法名, 消息内容
      _unityWidgetController?.postMessage(
        'MessageManagerObject', 
        'MessageFromFlutter', 
        message
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Flutter + Unity')),
      body: Stack(
        children: [
          UnityWidget(
            onUnityCreated: _onUnityCreated,
            onUnityMessage: _onUnityMessage,
            useAndroidViewSurface: true, // 关键：解决 Android 渲染黑屏问题
            borderRadius: BorderRadius.all(Radius.circular(20)),
          ),
          Positioned(
            bottom: 20,
            left: 20,
            child: ElevatedButton(
              onPressed: _rotateModel,
              child: Text("Rotate 3D Model"),
            ),
          ),
        ],
      ),
    );
  }
}

构建配置：避开这些“深坑”

代码写对了只是第一步，真正的噩梦往往开始于点击 Build 的那一刻。以下是我们总结的必须调整的配置项。

平台	常见错误	解决方案
Android	`NDK version not found`	在 `android/app/build.gradle` 中显式指定 NDK 版本（如 `ndkVersion "21.4.7075529"`），需与 Unity 安装版本一致。
Android	`kIsWeb is not defined`	确保 Flutter 版本与插件版本兼容，升级 `flutter_unity_widget` 到最新版（目前 v4.x 支持 Flutter 3）。
iOS	`Invalid Bitcode Signature`	在 Xcode 中将 Build Settings -> Enable Bitcode 设置为 `No`。Unity 导出的库通常不支持 Bitcode。
iOS	UI 渲染层级错乱	在 `Info.plist` 中添加 `io.flutter.embedded_views_preview` 为 `YES`（针对旧版 Flutter）。

警告： Android 端的 minSdkVersion 通常需要提升至 21 或更高，因为 Unity 的现代渲染管线不支持过旧的 Android 版本。

Conclusion

将 Flutter 与 Unity 结合并不是简单的叠加，而是一场关于渲染管线和进程间通信的博弈。通过合理的架构分层——Flutter 负责轻量级 UI，Unity 负责重量级 3D——我们可以构建出既具备原生应用流畅度，又拥有游戏级视觉效果的超级应用。接下来的工作，建议重点关注性能调优，特别是在低端设备上 Unity 视图的帧率限制与内存占用监控。