用Flutter做小游戏：Flame引擎与鸿蒙跨端开发全记录

大概两个多月前，我用 Flutter 做了一个叫 SkyTank 的战机大战小游戏，目标是同一套代码跑通 Android、iOS 和 HarmonyOS 6.0 三个端。做完之后最大的感受是：Flutter 做跨端小游戏这条路完全走得通，但跟用 Unity 或 Cocos 做游戏完全是两套思路，坑也不少。这篇文章就把整个项目的选型、设计、编码和上架环节里踩过的坑、验证过的方法都写出来，给想用 Flutter 做小游戏、尤其是想兼容鸿蒙生态的朋友一个可以跟着落地的参考。

我假定你至少有 Flutter 基础，知道 Widget、State、pubspec 这些概念，但不需要你有游戏开发经验。整个项目用到的关键技术点包括：Flame 轻量游戏引擎、Flutter 与鸿蒙原生通道的交互、sqflite 本地数据库与后端同步、以及多端构建时的环境配置问题。下面直接进入正题，按我实际开发的顺序来聊。

1. 为什么小游戏项目我会选择 Flutter 而不是 Unity 或 Cocos

1.1 从需求反推引擎选型

先说结论：如果你的目标平台明确包含 HarmonyOS 6.0，并且游戏玩法偏向 2D 轻度休闲，Flutter 是一个性价比极高的选择。我当时立项时的需求其实很清晰：需要一套代码覆盖安卓、iOS 和鸿蒙，游戏体量不需要 3D 特效，玩法是经典的纵版战机射击，交互以触控拖拽为主。

Unity 和 Cocos 在游戏生态上确实成熟，但有个现实问题：它们对接鸿蒙的流程需要额外的导出工具链。Unity 要装 Huawei 的插件，Cocos Creator 也需要对着鸿蒙工程手动配置一堆东西。而如果用 Flutter，官方和社区已经证明了 Flutter 引擎可以在鸿蒙上跑通，再加上鸿蒙原生工程的集成方式也就是标准的 ohos 工程导入依赖，整个链路会顺畅很多。

另外，我这个小游戏本质上是一个“带游戏玩法的 App”：它需要登录、支付、排行榜、本地存档这些非游戏功能。这类业务功能如果写在 Unity 里，说实话，做 UI 和市政服务的效率远不如 Flutter。Flutter 的强项是业务界面和交互，Flame 引擎恰好补足了游戏循环和组件管理的能力，两者结合很适合做“轻游戏 + 重运营”的产品。

1.2 Flutter 做轻量级小游戏的渲染路径与优势

很多人有个误解，觉得 Flutter 不是游戏引擎，做不了游戏。其实 Skia/Impeller 渲染引擎处理 2D 精灵图完全不在话下，关键看你用什么方式组织游戏循环。

最原始的做法是直接用 Flutter 的 AnimationController 驱动游戏循环，每帧 setState 更新游戏状态，再用 CustomPaint 或 Stack + Positioned 来决定绘制。这个方案能做出来，但代码会很乱，碰撞检测、对象生命周期、音效调度都要自己造轮子。

我最终引入了一个叫 Flame 的轻量级 2D 游戏引擎，它的核心价值不是给你提供图形渲染能力，而是帮你把游戏循环、组件树、碰撞检测、输入事件这些“游戏通用底层”封装好。Flame 的 GameWidget 可以当作一个普通 Widget 嵌入 Flutter 的 Widget 树里，这就意味着游戏页面和业务页面可以在同一个 Navigator 下无缝切换。

对比一下传统方案：

我选择 Flutter 还有一个重要原因：团队成员对 Dart 的熟悉程度远高于 C# 和 Lua。技术选型永远要综合考虑团队技能树，而不是只看引擎本身。

1.3 Flame 游戏引擎引入与架构分层

Flame 的集成非常简单，在 pubspec.yaml 里加依赖就行。我当时用的版本是 1.10 左右，现在应该有新版，接口大体兼容。

yaml复制dependencies:
  flutter:
    sdk: flutter
  flame: ^1.10.0
  sqflite: ^2.3.0
  path: ^1.8.0
  dio: ^5.3.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0

我的项目结构长这样：

code复制lib/
  main.dart                 # 入口，初始化数据库和全局状态
  game/
    sky_tank_game.dart      # 游戏主类，继承 FlameGame
    components/
      tank_player.dart      # 玩家战机组件
      enemy_spawner.dart    # 敌机生成器
      bullet.dart           # 子弹组件
      explosion.dart        # 爆炸特效组件
    physics/
      collision.dart        # 碰撞检测逻辑
  pages/
    home_page.dart          # 主菜单
    game_page.dart          # 游戏页面，嵌入 GameWidget
    rank_page.dart          # 排行榜页面
  services/
    storage_service.dart    # 本地数据库封装
    sync_service.dart       # 后端同步封装
  native/
    harmony_bridge.dart     # 鸿蒙原生通道封装

这个分层的好处是：Flutter 层完全不知道游戏内部用了 Flame，只知道 GameWidget 能打印游戏分数、暂停游戏；同理，Flame 层也不关心数据是存在本地还是同步到后端，只管把分数通过回调抛出去。这样后续如果想把游戏内核换成别的引擎，或者把业务层拆成纯 Flutter 模块，改动成本都很低。

2. SkyTank 战机大战的整体设计与核心玩法实现

2.1 游戏逻辑分层：从 Game Loop 到状态管理

做游戏跟做普通 App 最大的区别是：普通 App 是“事件驱动”，而游戏是“帧驱动”。每一帧都要重新计算位置、检测碰撞、渲染画面。Flame 把这件事封装成了 Game Loop，你只需要重写 update 和 render 两个方法。

我的 SkyTank 游戏主类大概是这样的：

dart复制class SkyTankGame extends FlameGame {
  late TankPlayer _player;
  late EnemySpawner _enemySpawner;
  int _score = 0;
  bool _isGameOver = false;

  @override
  Future<void> onLoad() async {
    // 设置背景
    await _loadBackground();
    // 创建玩家战机
    _player = TankPlayer();
    add(_player);
    // 创建敌机生成器
    _enemySpawner = EnemySpawner();
    add(_enemySpawner);
    // 监听碰撞事件
    add(CollisionBlock());
  }

  @override
  void update(double dt) {
    super.update(dt);
    if (_isGameOver) return;
    _checkCollisions();
  }

  void addScore(int points) {
    _score += points;
    // 通过回调通知 Flutter 层更新 UI
    scoreNotifier.value = _score;
  }
}

在状态管理上，我没有用 Bloc 或 Riverpod 那套重型方案，而是用 ValueNotifier 配合 Provider。游戏内频繁变化的分数、生命值用 ValueNotifier，页面级的路由和设备状态用 Provider。原因很简单：游戏里的状态更新频率太高，一秒钟可能有几十次 UI 刷新，如果走完整的 Stream 管道会带来不必要的开销。

2.2 战机控制、敌机生成、碰撞检测的实现细节

玩家战机的控制我采用了两种方式：一是基于手势的“按住位置跟随”——手指停留在屏幕的某个位置，战机平滑移动过去；二是拖拽模式，手指拖动时战机实时移动。两种模式在玩法和手感的取舍上差别很大，我在项目里做了一个设置项让用户自己选。

从实现上说，Flame 的输入监听非常简单，通过重写 onDragUpdate 或者读取 **游戏实例的指针位置即可。核心代码如下：

dart复制class TankPlayer extends SpriteComponent with HasGameReference<SkyTankGame> {
  double moveSpeed = 300; // 像素/秒
  
  @override
  void update(double dt) {
    super.update(dt);
    // 获取当前指针位置
    final pointer = game.camera.viewport;
    if (game.touchInput.isActive) {
      final pos = game.touchInput.latestPointer!.eventPosition.global;
      // 平滑移动目标点
      final target = Vector2(pos.x, position.y);
      final direction = target - position;
      if (direction.length > 2) {
        position.add(direction.normalized() * moveSpeed * dt);
      }
    }
    // 限制战机不出边界
    position.x = position.x.clamp(virtualWidth * 0.05, virtualWidth * 0.95);
  }
}

敌机生成器的设计就用了一个定时器逻辑：每隔一段时间在屏幕上方随机位置生成一架敌机，敌机沿直线或波浪路径向下移动。不同难度会改变生成间隔和敌机速度。

碰撞检测我用的是 Flame 的 CollisionCallbacks mixin，然后在组件上添加 CollisionShape。这样组件间一旦碰撞就会自动回调 onCollision 方法。要注意的一个坑是：Flame 的碰撞检测默认是矩形包围盒，战机这种不规则形状如果直接用矩形做碰撞，容易出现“明明子弹打中了机身空白处却判定命中”的情况。我在项目里把子弹和敌机的碰撞盒都缩了一圈，用经验值调到手感合适的范围。这里贴一段关键代码：

dart复制class Bullet extends SpriteComponent with CollisionCallbacks, HasGameReference<SkyTankGame> {
  Vector2 velocity = Vector2(0, -500);
  
  @override
  void onCollision(Set<Vector2> intersectionPoints, PositionComponent other) {
    super.onCollision(intersectionPoints, other);
    if (other is EnemyPlane) {
      other.takeDamage(1);
      game.addScore(10);
      removeFromParent();
      game.spawnExplosion(position);
    }
  }
}

2.3 计分、音效与资源管理的落地方式

计分看似简单，但机制上有个容易忽略的细节：不同敌机的分值、连击加成、关卡倍率。我在项目里把这些配置统一放到了一个 JSON 配置文件里，而不是硬编码在代码中。这样调整数值平衡时不用重新发布，也可以配合后端做 A/B 测试。

关卡配置的示例：

json复制{
  "levels": [
    {
      "id": 1,
      "enemySpawnInterval": 2.5,
      "enemySpeed": 120,
      "enemyHp": 1,
      "scoreMultiplier": 1
    },
    {
      "id": 2,
      "enemySpawnInterval": 2.0,
      "enemySpeed": 160,
      "enemyHp": 2,
      "scoreMultiplier": 1.2
    }
  ]
}

音效这块，Flame 提供了一个 audio 插件，支持从 assets 加载音频并控制音量和循环。我在项目里用了 flame_audio 加上一个 AudioService，统一管理射击、爆炸、背景音乐的音量开关，并且把音量设置存到 SharedPreferences 里，用户改一次设置就长期生效。

资源管理上最关键的一课是：纹理图集（Sprite Sheet）能在很大程度上降低包体和加载时间。我一开始每个素材都是独立 PNG，结果内存占用和加载耗时都很大。后来把战机、敌机、子弹、爆炸动画都合并成一张大图，用 Flame 的 SpriteSheet 来切，游戏加载时间从 2 秒降到了 300 毫秒以内。

3. 跨端适配实战：从 Android/iOS 到 HarmonyOS 6.0

3.1 鸿蒙 6.0 上跑 Flutter 的兼容性现状

先直接说结论：Flutter 在 HarmonyOS 6.0 上跑普通 UI 应用和轻量小游戏都没有问题，但需要走 Ohos 工程打包，不是直接用 Flutter 默认的 Android 打包命令就能输出 hap 包的。

目前社区里已经有一套比较成熟的 Flutter 鸿蒙 SDK，通过 OpenHarmony 适配方案，Flutter 引擎可以编译成鸿蒙的 hap 包。我用的版本是基于 Flutter 3.7 的适配版本，对应的鸿蒙 SDK 是 HarmonyOS NEXT 6.0。这个适配版本已经支持了大部分核心插件，尤其是 dart:ui 层和平台通道。

如果你要跑这个项目，需要做以下准备：

1. 下载支持鸿蒙的 Flutter SDK 分支，并配置到环境变量。
2. 安装 DevEco Studio，用来打开和编译 ohos 工程。
3. 用命令 flutter build hap 或者通过 DevEco 的图形界面打包。

我在真机上跑的结果是：渲染性能流畅，项目里用到的精灵动画和碰撞检测都能在 60fps 下运行，内存占用约 150MB，处于可接受范围内。当然，个别插件如果原生实现没有适配鸿蒙，比如某些第三方广告 SDK，就需要走平台通道自己做桥接。

3.2 鸿蒙侧的 IAP 支付、微信登录等原生能力接入

做小游戏绕不开支付和登录。在鸿蒙 6.0 上接入 IAP 支付，跟 Android 的思路类似，但走的 API 完全不一样。我这里分享一个规律：先把 Flutter 层的接口定好，再去实现鸿蒙原生侧。

Flutter 侧代码：

dart复制class HarmonyBridge {
  static const MethodChannel _channel = MethodChannel('com.skytank/harmony');

  // 拉起鸿蒙 IAP 支付
  Future<String> purchase(String productId) async {
    try {
      final String result = await _channel.invokeMethod('iapPurchase', {
        'productId': productId,
        'amount': 6,
      });
      return result;
    } on PlatformException catch (e) {
      print('支付失败: ${e.message}');
      return 'failed';
    }
  }

  // 微信登录
  Future<Map<String, String>> wxLogin() async {
    final Map<String, String> result = await _channel.invokeMethod('wxLogin');
    return result;
  }
}

鸿蒙侧用 ohos 的 IAP SDK 实现 MethodChannel 的 iapPurchase 方法。这里要注意的是，鸿蒙的支付 SDK 对支付结果的回调是异步的，而且要求业务侧做幂等处理——如果用户支付成功后网络断了，你需要用订单号向服务端查询来最终确认结果，不能只依赖回调。

微信登录在鸿蒙上有两个方向：一个是走微信开放平台的“App 登录”，另一个是走鸿蒙系统的账号授权。我最终选了前者，因为微信登录的核心目的是让用户绑定微信身份，走微信的标准 SDK 语义更清晰。接完之后还有个细节：鸿蒙的回调Activity和Flutter的Activity是同一个上下文，初始化微信 SDK 时要确保主线程注册。

3.3 本地数据库与后端同步的轻量方案

游戏需要保存用户战绩、设置、解锁记录等数据。Flutter 的跨端数据库方案我最终选了 sqflite，它在 Android 和 iOS 上都稳定，关键是它在鸿蒙上也有对应的适配实现，或者你可以直接用 sqflite_common_ffi 通过 Dart 原生实现绕开平台通道。

为了保险起见，我的项目里加了一层存储抽象：

dart复制abstract class StorageService {
  Future<void> init();
  Future<List<ScoreRecord>> getLocalScores();
  Future<void> saveScore(ScoreRecord record);
  Future<void> syncFromServer();
}

class LocalStorageService implements StorageService {
  late Database _db;

  @override
  Future<void> init() async {
    final path = await getDatabasesPath();
    _db = await openDatabase(
      '$path/skytank.db',
      version: 1,
      onCreate: (db, version) async {
        await db.execute('''
          CREATE TABLE scores(
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            player_name TEXT,
            score INTEGER,
            level INTEGER,
            created_at TEXT
          )
        ''');
      },
    );
  }
  // 其他方法实现...
}

本地数据库存原始数据，后端同步只做增量拉取和上传。同步策略我用了最简单的“时间戳 + 全量拉取”：每次游戏结束后写入本地，等进入排行榜页面时，先把本地未同步的数据 POST 到服务端，再 GET 全量排行榜。对于小游戏这种低频写、高频读的场景，这个方案足够稳定，不需要引入复杂的离线队列。

后端我用的是最简单的 Dart shelf 或 Node.js 写一个 JSON API，部署在任何云服务上即可。Flutter 侧用 Dio 发请求，Dio 的拦截器很方便，可以统一处理 token 注入和 401 跳转。

4. 开发环境搭建与高频报错排查实录

4.1 Flutter SDK 安装与多端环境配置要点

如果你是从零开始配置，我建议按这个顺序来：先装标准版 Flutter SDK，再装鸿蒙版 Flutter SDK。因为标准版是你日常调试 Android/iOS 的基础，鸿蒙版只是在打包 hap 时才需要。

安装时最容易踩的坑是环境变量。很多新手在终端里敲 flutter --version 仍然显示系统自带的老版本，就是因为 PATH 里新旧 SDK 冲突或者终端没重启。我的建议是：在 .bashrc 或 .zshrc 里把 Flutter SDK 的 bin 目录放在最前面，装完之后新开一个终端再验证。

Windows 上还要注意 Visual Studio 的问题。如果你同时装了 Visual Studio 2022 和多个桌面开发组件，在用 Flutter 编译 Windows 桌面版或跑 flutter doctor 时会碰到类似：

code复制CMake Error at CMakeLists.txt:3 (project):
  Generator Visual Studio 16 2019 could not find any instance of Visual Studio.

这个报错本质是 CMake 和 Visual Studio 版本匹配不上，解决方法是：装上 Visual Studio 2022 时勾选“使用 C++ 的桌面开发”工作负载，并且修改环境变量 CMAKE_GENERATOR 为 Visual Studio 17 2022。如果项目里已经有 CMakeCache.txt，把 build 目录整个删掉，让它重新生成。

手机端真机调试还有一个很容易被忽略的点：iOS 需要正确处理好证书，Android 和鸿蒙需要开启 USB 调试，但如果用的是鸿蒙的调试工具，端口和 Android 的 5555 是不一样的，需要单独配置。

4.2 常见编译与运行报错速查

这一部分我把开发期间遇到的高频报错整理成了一张速查表，都是真实可复现的场景和对应解法：

这里重点说一下 showLicensePage 的主题颜色问题。Flutter 自带的 LicensePage 用起来很方便，但默认的 AppBar 主题经常会跟你自己 App 的主题不一致，尤其在切换了 Material 3 之后。我当时在产品里点击“隐私政策与第三方许可”后，打开的页面突然变回蓝色 AppBar，非常突兀。解决思路是：不要直接调用 showLicensePage，而是自定义一个 Scaffold，里面用 LicensePage 作为 body：

dart复制Future<void> showCustomLicensePage(BuildContext context) async {
  await Navigator.push(context, MaterialPageRoute(
    builder: (context) {
      return Scaffold(
        appBar: AppBar(
          title: Text('开源软件许可'),
          backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        ),
        body: LicensePage(
          applicationName: 'SkyTank',
          applicationVersion: '1.0.0',
        ),
      );
    },
  ));
}

这样页面主题就完全跟 App 保持一致了。

4.3 容易被忽略的小部件细节

在开发过程中我还遇到过两个很典型的 UI 细节问题，属于看文档看不出来、实际跑起来才发现的类型。

第一个是 CheckboxListTile 的文字距离按钮太远。默认情况下，CheckboxListTile 的 title 和复选框之间有很大一段间距，尤其是当内容只有一行文字时，视觉上会觉得分布很不均匀。这是因为 ListTile 默认会把次要元素推到最右侧。解决方法有两个：一是手动设置 controlAffinity: ListTileControlAffinity.leading，把复选框挪到最左边；二是自定义一个 Row 结构，完全掌控布局。我在设置页里用了前者，简单有效。

第二个是 Flutter Web 上字体变小的问题。这通常是因为 Web 端默认字体族跟你开发时本地的字体渲染不一样，特别是中文场景下，如果没有引入平台字体，浏览器会自己选择一套回退字体。我的经验是：小游戏项目不要在文本上依赖系统字体，直接把字体文件（ttf 或 otf）放进 assets，然后在 pubspec 里注册，这样所有端显示效果一致。

yaml复制fonts:
  - family: GameFont
    fonts:
      - asset: assets/fonts/PixelFont.ttf

在页面里通过 fontFamily: 'GameFont' 指定即可。

5. 小游戏上架前的性能优化与测试

5.1 包体、内存与帧率的优化实践

小游戏有一个天然门槛：包体要小，启动要快，帧率要稳。我用 Flutter 做完第一版后，打出来的 Android APK 有 28MB，对于一个小游戏来说偏大了，于是做了一轮定向优化。

首先是资源压缩。我把所有 PNG 图片统一走了一遍压缩流程，能转 WebP 的转 WebP，不能转的至少把颜色位数降低。单单这一步，资源目录就从 18MB 降到了 8MB。

其次是代码裁剪。flutter build apk --split-per-abi 可以将不同 CPU 架构的 so 文件拆开，只保留 arm64-v8a 的情况下包体能再降三分之一。对于只发布到手机端的游戏来说这是必须开的。

第三是运行时内存。Flame 游戏里最占内存的不是纹理，而是精灵对象。如果每架敌机都实时 new 一个 SpriteComponent，内存会有一定压力。我的做法是对象池复用：敌机子弹、爆炸特效这些高频创建销毁的对象，统一用对象池管理，在对象销毁时只隐藏不析构，下次直接复用。

性能监控方面，我用 Flutter DevTools 的 Performance Overlay 来观察真实帧率，至少在低端机上保证了 50fps 以上才敢说“测试通过”。

5.2 从 SkyTank 出发：一键多端发布的工程化经验

最后聊聊工程化。Flutter 的优势是跨端，但“跨端开发”和“一键多端发布”之间还有一段距离。我在项目里做了两个关键改造：

第一个是构建脚本。我用 Dart 写了一个命令行工具，统一封装了 Android、iOS、鸿蒙的构建命令。这样团队里的人不需要记一长串命令，跑 dart run tool/build.dart --platform=harmony --mode=release 就能拿到对应的产物。脚本里还可以自动处理版本号递增、资源拷贝、签名配置，避免人为出错。

第二个是接口环境的区分。开发、测试、预发、生产四个环境的域名和开关都要能通过编译参数注入。我用的方案是定义 AppConfig 类，通过 --dart-define=API_HOST=xxx 在构建时传入，这样代码里没有硬编码的测试地址，也不会出现“上线前忘记改域名”的尴尬。

测试策略上，因为是小游戏，我没有投入大量自动化测试，而是做了一个很简单的冒烟测试脚本：游戏启动后自动进入游戏页，模拟发射 30 发子弹、生成 10 架敌机，然后自动退出，检查是否有崩溃和异常日志。这个脚本通过 flutter drive 运行，每次发版前跑一遍，能拦住大部分低级问题。

拿我这个项目举例，最终发版流程大概是：代码合并到 main 分支后，跑一遍冒烟测试，然后依次执行 Android、iOS、鸿蒙的构建脚本，产物上传各家后台等待审核。整体流程从最开始的半天人工操作，压缩到了 30 分钟左右的半自动流程。

这个项目之后，我还有一个更深入的体会：跨端小游戏的核心难点不在“会不会写游戏”，也不在“会不会 Flutter”，而是在于你能不能把游戏引擎、业务框架、原生平台通道和发布流程这四套体系在脑子里同时运转。Flutter + Flame + 鸿蒙适配的组合目前已经不是实验性方案，而是可以拿来接商业项目的成熟路线。如果你也在做类似的小游戏，希望这篇复盘能帮你少走几个月的弯路。