最近在折腾Flutter for OpenHarmony的游戏合集类App，踩了不少坑，也积累了一些可复现的经验。这个项目本身不复杂，就是做一个包含多个小游戏的App，先落地的是扫雷模块，重点难点在棋盘数字的生成与显示。但越是不复杂的项目，越能体现跨平台框架在国产系统上的适配状况到底如何。这篇文章就把整个实战过程拆开讲清楚，尤其是扫雷数字显示这部分，从算法逻辑到UI实现，再聊到OpenHarmony的适配细节，给想在这条路上试试水的朋友一个参考。
先说清楚这个项目能解决什么。扫雷这个游戏，核心玩法就是点开格子后，每个格子要显示出周边地雷的数量，这个数字系统是整个游戏逻辑的基石，也是UI交互最密集的部分。如果你正在做Flutter跨平台开发，或者刚接触OpenHarmony应用开发，或者纯粹想看看Flutter在非Android、iOS平台上的编译效果，这篇内容都适合你。我会把整个项目从设计到落地拆成一块一块来讲，确保你看完能从零开始复现。
1. 项目整体设计思路拆解
1.1 为什么选Flutter而不是ArkUI原生开发
接到这个项目的时候，OpenHarmony的原生开发框架ArkUI已经比较成熟了。但最终还是决定用Flutter来做，主要是三个考虑。
第一是团队技术栈复用。团队里多数人以前是做Flutter的，对Dart语言和Flutter的渲染机制比较熟。如果切到ArkUI，等于要重新学一套声明式UI框架和TypeScript生态，学习成本会直接反映到排期上。
第二是跨端保持一致性的诉求。这个游戏集合App后面计划覆盖更多轻量设备，不仅仅是手机，可能还有平板和带屏的IoT设备。Flutter在适配不同屏幕尺寸和硬件平台上的经验更丰富，一套代码多个平台跑的能力对后续扩展很有帮助。
第三，Flutter对OpenHarmony已经有一份可用的适配方案。虽然Flutter官方没有原生支持OpenHarmony，但社区和OpenHarmony团队一直在维护一套带有平台通道支持的Flutter分支。这套分支现在已经能满足常规的UI渲染和基础交互需求，扫雷这种网格类界面完全不在话下。
1.2 游戏集合App的架构规划
既然是集合类App，就不能只写一个扫雷就完事。我提前规划了一个简洁的分层结构，方便后面往里面加新游戏。
最外层是启动器和游戏列表页，负责展示所有已收录的游戏入口。目前规划了扫雷、拼图、数独、记忆翻牌这几个方向，扫雷是第一个落地的。
再往下一层是通用游戏框架。这里统一处理了页面导航、游戏状态持久化、成绩记录、主题切换这些和具体玩法无关的公共能力。比如扫雷和拼图都要用到的计时功能，就抽成了公共组件，不放在某个游戏内部。
最底层是按游戏拆分的独立模块，每个模块拥有自己的状态管理、数据和UI组件。模块之间不做任何直接依赖，都是通过公共接口通信的。这样以后要删除或者新增一个游戏，完全不影响其他模块。
1.3 扫雷模块的核心需求分析
扫雷说简单也简单，就三个核心需求：棋盘生成、数字计算、翻开交互。围绕数字显示这个重点，我梳理了一份更细的需求清单：
- 棋盘尺寸可配置，经典9x9、16x16，还有自定义模式
- 地雷数量按难度动态生成，保证可玩性
- 每个非地雷格子要显示周围8格的地雷总数
- 数字为0的格子点击后自动展开连片空白区域
- 长按格子可以标记地雷，数字显示要区分普通数字和标记状态
- 游戏状态包括进行中、胜利、失败，需要清晰反馈
数字显示看似是最后一环的UI问题，但实际牵扯到整个数据模型的设计。比如数字对应的颜色规范、0的特殊处理、翻开和未翻开状态的切换，这些需求在动手编码前就要全部考虑到位。
2. 扫雷核心算法：地雷布局与数字计算
2.1 经典扫雷规则回顾
扫雷的规则非常简单：玩家点击棋盘上的一个格子，如果是地雷就游戏结束；如果不是地雷，会显示一个数字，代表这个格子周边八个格子里面有多少颗地雷。如果数字是0，表示周边没有雷，那么程序会把这个格子周边所有安全格子也一并翻开，直到遇到数字大于0的边界为止。
这个规则决定了整个数据模型的设计方向。我们需要两张关键的数据视图：一个是地雷分布图，决定游戏流程；另一个是数字分布图，决定UI显示的内容。这两张图在棋盘初始化的时候可以一次性算好，后面每次点击就直接查询。
2.2 地雷随机布局的实现
地雷布局的核心是随机算法。很多新手喜欢用shuffle打乱数组的方式来做，就是把所有格子排成一排，前面N个标记为地雷，后面标记为非地雷，然后对整个数组做随机打乱。这个方案虽然简单，但生成的布阵有时候会出现地雷扎堆或全部散开的情况，可玩性一般。
我更推荐的做法是逐个生成随机坐标，并保证每个地雷位置唯一。通过双重循环遍历整个棋盘，用Random.nextInt生成行列索引，如果该位置已经有过雷就重新生成。实测下来这个方案的分布更均匀一些，玩家初期点击不容易碰到"开局即炸"的恶劣情况。
开局保护机制也是必须的。经典扫雷里第一次点击的格子绝不能是地雷，需要在生成地雷之前就把首次点击的坐标传进来，执行生成逻辑时排除这个位置以及它周边的8个格子。实现方式很简单，生成地雷前先把这些位置标记为不可放置就行了。
2.3 周边数字计算的两种思路
生成完地雷后，下一步就是计算每个安全格子周边的地雷总数。我尝试了两种实现方式，各有优劣。
第一种是逐格扫描法。双重循环遍历棋盘上每一个格子，如果这个格子不是地雷，就检查它周围8个格子，数出地雷数量，写入对应的数字字段。这个方法思路直观，代码写起来很顺手，时间复杂度是O(n)乘以常数8，对于扫雷这种小棋盘来说性能完全不是问题。
第二种是地雷扩散法。先遍历所有地雷，对每颗地雷周围的8个位置分别加1。也就是说，如果一个安全格子同时被三颗雷"碰到"，那么它的数字就是3。这个方法代码量更少，也避免了重复判断"当前位置是不是雷"的逻辑。
实际项目里我用了第二种。因为第二种方法的边界处理更统一，只需要在坐标合法性判断里判断一次，不需要在扫描的时候同时处理"当前位置是雷"和"边界格子"两层逻辑。两种方法在结果上是完全等价的，如果你喜欢哪种就写哪种，没有标准答案。
2.4 翻开逻辑与递归展开
翻开一个格子，如果数字是0，需要自动展开周围的空白区域。展开逻辑我这里用的是经典的BFS广度优先搜索。
具体做法是维护一个队列，先把用户点击的格子入队，然后循环处理队列。每次取出一个格子，如果它已经被翻开就跳过，否则标记为翻开。如果这个格子的数字为0，就把周围8个格子加入队列。这样一级级扩散，直到所有连通的空白区域都被翻开，边界上遇到数字大于0的格子就停下来，这个格子本身也会显示数字。
递归DFS也可以实现同样的效果，但棋盘局域较大的情况下递归深度可能会导致栈溢出风险，即便在Colyseus上不太可能出事，BFS的写法也更稳妥。用队列处理还有个好处是能方便地统计本次翻开的总格子数，做动画或者计分的时候直接拿这个数用。
3. Flutter中数字显示的UI实现方案
3.1 棋盘绘制：GridView与CustomPaint选型
数字显示是UI层最核心的部分，但承载数字的棋盘容器一样关键。Flutter里画一个网格棋盘，通常有两种方案。
第一种是用GridView.builder。每个格子是一个独立Widget，天然支持点击事件、动画和主题定制。这个方案的优势在于组件化程度高，代码可读性好，后续如果要在某个格子上加特效动画很方便。缺点也很明显：如果棋盘很大，Widget数量会比较多，虽然16x16也才256个，对Flutter来说压力不大，但如果是50x50这种超大连连看棋盘，就要考虑复用问题了。
第二种是用CustomPaint自绘。通过canvas.drawRect和canvas.drawText直接在画布上画格子，性能是最好的，但代码复杂度和维护成本都高了不少。而且自绘方案处理点击区域映射会比较麻烦，需要自己算坐标转换。
我这个项目选的是GridView.builder，关键原因是扫雷的交互特别看重点击反馈，用Widget方案可以直接复用Flutter的InkWell涟漪效果和AnimatedContainer做位移动画，这些在自绘方案里都要自己实现，得不偿失。
3.2 单元格状态的建模
一个格子的状态比较复杂，除了最基本的"有没有雷"以外，还要区分很多玩法和UI状态。我定义了一个枚举类来管理：
- 未翻开、未标记：初始态，界面显示为一个凸起的小方块
- 未翻开、已标记：玩家长按标记了旗帜，表示怀疑这里可能有雷
- 已翻开、数字格：显示数字，根据数字不同呈现不同颜色
- 已翻开、地雷格：游戏失败时才会出现，红色底图加灰色地雷图标
这些状态和数据层是分离的。数据层只关心isMine、number、isRevealed、isFlagged这四个字段，UI层再根据这些字段组合出实际显示效果。这样做的好处是逻辑和界面解耦，方便在UI层做状态流测试，也方便以后接入新的显示需求（比如问号标记）。
3.3 数字显示的具体实现
数字本身的显示我用的是Text组件，字体大小和颜色根据棋盘尺寸动态调整。经典扫雷的数字颜色是有传统规范的，比如1是蓝色、2是绿色、3是红色、4是深蓝色，这个配色在Windows扫雷里深入人心，我索性沿用这套配色，也算是一种情怀。
Color getNumberColor(int number) { switch (number) { case 1: return const Color(0xFF1976D2); case 2: return const Color(0xFF388E3C); case 3: return const Color(0xFFD32F2F); case 4: return const Color(0xFF7B1FA2); default: return const Color(0xFF455A64); } }为了让数字在格子里垂直水平居中，我用了一个Center包住Text，并且通过FittedBox做自适应缩放。这样不管棋盘尺寸怎么调，数字都不会出格。还有一个细节是字体加粗和防锯齿处理，数字在屏幕上的清晰度会直接影响玩家体验，我用的是FontWeight.bold加上fontFeatures里的tabularFigures，让数字宽度一致，避免跳动。
0的格子要单独处理。数字为0的格子翻开后，里面不需要显示任何文字，只呈现一个浅色背景，视觉上干净舒服。同时0格子是空白区域自动展开的起点，所以UI上要稍微突出一点平滑过渡效果，我用了一个200毫秒的透明度动画从深到浅渐变，模拟"翻开"的瞬间感。
3.4 状态管理与点击交互
扫雷的状态变化集中在棋盘这一层，不需要引入Redux级别的重型状态管理库。我用的是Flutter原生的ChangeNotifier加AnimatedBuilder方案：整个棋盘是一个ChangeNotifier，格子翻开的动作会触发notifyListeners()，然后AnimatedBuilder监听这个通知重建棋盘。
class MineBoardModel extends ChangeNotifier { List<List<MineCell>> cells; bool isGameOver = false; void revealCell(int row, int col) { // 翻开逻辑 notifyListeners(); } }这个方案已经能很好的覆盖扫雷这种单一页面的状态管理需求。代码结构简单，调试方便，Hot Reload的时候状态还能保留，开发体验非常友好。
3.5 数字显示的动画细节
数字出现的动画虽然是小细节，但很能体现App的精细度。我在数字格翻开时加了一个缩放入场效果：从0.8倍缩放到1.0倍，加上100毫秒的淡入。这个动画成本极低，但会让玩家产生"格子翻开是有反馈"的感觉，交互体验提升明显。
AnimatedScale( scale: cell.isRevealed ? 1.0 : 0.8, duration: const Duration(milliseconds: 120), curve: Curves.easeOut, child: AnimatedOpacity( opacity: cell.isRevealed ? 1.0 : 0.0, duration: const Duration(milliseconds: 100), child: cellText, ), )动画的触发条件就是格子的isRevealed状态。平时这些数字的透明度为0，不占交互事件，翻开后自动执行动画。这里要注意的是性能问题：棋盘上同时有几十个格子在播放动画，如果每个格子都用独立的动画Controller可能会导致性能下降，所以用AnimatedScale和AnimatedOpacity这种隐式动画组件，让Flutter内部统一管理，开销小很多。
4. OpenHarmony平台适配与构建配置
4.1 Flutter for OpenHarmony的现状
Flutter官方框架并不直接支持OpenHarmony，但可以通过社区维护的版本进行适配。在开始项目前，需要提前了解哪些功能可用，哪些不可用。当前正好碰到一个特殊情况：新版Flutter的渲染引擎转向Impeller，这会影响到在OpenHarmony上的兼容性。如果打开的Flutter for OpenHarmony版本默认开启Impeller，建议将渲染引擎切换回Skia，以保证在OpenHarmony上的稳定表现。
这个兼容性问题的处理方式是在项目的main.dart入口处动态判断平台，如果是OpenHarmony环境就强制使用Skia渲染。虽然这样会少了一点Impeller带来的性能提升，但稳定性优先，尤其是在扫雷这个场景中，所有的UI都是简单图形和文本，Skia的渲染能力已经完全足够了。
4.2 环境安装与项目配置
Flutter for OpenHarmony的环境配置有一些猫腻，可以直接参考社区提供的方式。我在配置过程中发现几个容易出错的点值得单独说。
SDK版本选择很重要。OpenHarmony的API版本演进很快，不同版本之间的API差异会让同一套Flutter代码出现不同的编译结果。建议尽量选择与Flutter for OpenHarmony适配版本对应的SDK版本，不要一上来就装最新的API版本，会很被动。
# 环境变量配置示例 export DEVECO_SDK_HOME=/path/to/ohos-sdk export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn配置好环境变量后，需要在pubspec.yaml里加上对OpenHarmony平台的支持。这一步比较特殊，因为普通的Flutter项目默认只创建android、ios、web这些平台的目录，OpenHarmony的工程目录需要手动生成。用Flutter for OpenHarmony分支提供的工具初始化项目后，会自动生成ohos目录，这个目录就是OpenHarmony工程入口。
4.3 真机调试与运行时问题
真机调试主要用两种方式：USB连接和无线调试。OpenHarmony设备的ADB端口和Android有些差异，连接后需要通过hdc工具来验证设备是否被识别。这和Android开发中用adb的工具逻辑很相似，核心是不断端对端地确认连接状态。
运行阶段最大的坑是权限申请。OpenHarmony对应用权限管得比较严，扫雷这个游戏本身不需要网络权限，但如果在游戏里集成了统计功能或者排行榜功能，就会涉及到网络权限声明。调试阶段这些权限不声明往往也能跑，但如果要做成正式应用分发，权限配置必须提前做好，否则某个功能在特定场景下会静默失败。
另外要注意的是OpenHarmony的ArkUI组件和Flutter的Widget之间的交互。有些系统能力比如振动反馈、系统弹窗，需要通过平台通道来调用。虽然扫雷里没用到这些，但如果想在游戏失败的时候用振动来增强反馈，就要写平台通道代码，在OpenHarmony的原生侧实现相应的功能调用。
5. 常见问题与排查技巧实录
5.1 数字显示异常排查
数字显示异常分几种情况。最典型的是"数字永远不变或一直显示为0"的问题，这时候要优先检查数据层：地雷数组是否成功初始化了？number字段在生成地雷后有没有更新？
我遇到过的一个诡异问题是，个别格子的数字会错位，比如格子坐标是(3,5)，但显示的内容却是(4,5)的数字。最后排查发现是GridView.builder的itemCount和索引映射出现了偏差，因为我在中间插入了排行榜相关的跳转逻辑，改变了列表的结构。解决的办法是彻底放弃基于索引的映射，改为在itemBuilder里通过格子坐标的逆运算获取当前位置，从根本上避免错位。
5.2 棋盘绘制性能优化
如果在低端设备上运行，棋盘绘制可能会出现卡顿，尤其是连续翻开大量格子的时候。优化方向有两个。
第一个是减少不必要的重建。把每个格子包在const构造函数里，或者使用RepaintBoundary阻止棋盘以外区域的频繁重绘。RepaintBoundary的作用是把棋盘这个区域单独隔离成一层，棋盘内的动画不会触发页面其他区域的重绘，对性能提升很明显。
第二个是限制动画的触发范围。翻开操作同一时间最多并发十几个动画，这个量级没问题，但如果在两个方向快速连续点击，动画队列会瞬间累积很多任务。我加了一个简单的节流逻辑，每次处理翻开操作前判断队列长度是否超过一个阈值，超过就丢弃这次动画播放，直接显示最终状态。
5.3 热重载与开发调试技巧
Flutter for OpenHarmony分支对Hot Reload的支持不如标准Flutter那么成熟，实测下来大部分情况下能用，但偶尔会出现状态丢失甚至白屏的情况。开发时我建议多做Hot Restart而不是Hot Reload，虽然慢一点，但状态一致性更高。
调试OpenHarmony上运行时的日志输出也有点区别。Flutter层的日志在运行flutter run的终端里能看到，但如果要查OpenHarmony原生侧的问题，就得去Ohos工程里看日志输出，日志级别和过滤规则都不同，需要来回对照。
有一点很重要：扫雷的"地雷生成"逻辑里如果用到了Random库，在不同设备上的随机数行为是一致的吗？答案是不完全一致。Dart的Random默认是基于物理随机数源的，如果真机上某些型号每次重启App都会生成完全相同的随机序列，就可能影响开局差异性。这个概率极低，但如果你要复现某些问题，记得固定一个随机种子来调试。
5.4 其他常见问题速查
- 真机上字体会发虚：检查是否在
TextStyle里显式设置了fontFamily，OpenHarmony上中文字体渲染如果不指定字体，默认可能使用系统英文数字字体，发虚是常见的坑，建议显式指定系统的中文字体族。 - 数字颜色过浅看不清：经典扫雷的配色在亮色背景上没问题，但OpenHarmony的默认主题可能是深色，需要把棋盘背景固定为浅色，或者为深浅模式分别定义数字配色。
- 点击没反应：检查格子是否被某个透明的
Container挡住了。扫雷棋盘用GridView.builder包在多个层级里，很容易因为Stack的层级关系导致点击事件被拦截。 - 编译报错找不到"ohos"相关包：大概率是SDK路径没配置正确，重新检查
local.properties和build-profile.json5里的SDK路径。
6. 实测体验与后续扩展
6.1 在模拟器和真机上的效果对比
我一共在三种环境下做了验证：OpenHarmony的模拟器、低配开发板的真机、以及一台普通的手机。模拟器上运行效果最流畅，动画完全不掉帧；低配开发板上渲染稍慢，但扫雷这种简单场景依然能稳定60fps；手机真机的兼容性最好，除了一开始提到的渲染引擎切换问题外，其他没遇到明显的障碍。
Flutter for OpenHarmony这套方案，目前应付游戏集合App这种轻渲染场景已经完全是够用的水平了。如果未来要上3D或者重度物理模拟类游戏，建议还是走原生渲染引擎的路线，Flutter在这个领域还不太合适。
6.2 数字显示逻辑的可复用性
别看扫雷的数字显示只是个简单的Text组件，它的扩展价值体现在两个方向。第一是这个UI模式的复用：游戏集合里后面马上要做的数独，同样需要数字格子的状态管理、点击反馈和主题化配色，已经能直接复用一套基础组件。第二是数字生成算法的抽象：扫雷的数字计算本质是一套基于邻域遍历的空间统计算法，把它抽成一个独立的工具类后，在拼图、连连看这类需要判断相邻关系的游戏里也能通用。
下面是我在实际项目中做的一个简单抽象，目前已经用在数独模块里了：
class NeighborCounter { static int countMines(List<List<int>> board, int row, int col) { int mineCount = 0; for (int i = -1; i <= 1; i++) { for (int j = -1; j <= 1; j++) { if (isInside(board, row + i, col + j) && board[row + i][col + j] == 1) { mineCount++; } } } return mineCount; } }6.3 后续功能扩展的思路
扫雷这个模块做完后，后面至少还有三个方向可以继续深耕。第一个是难度分级和自定义棋盘：把9x9、16x16和自定义宽高、雷数全部做成配置项，基础的数据结构和UI都已经支持了，改起来成本很低。第二个是计时和成绩排行榜：需要一个本地存储方案，OpenHarmony上SharedPreferences的Flutter插件有对应的适配版本，键值对存储排行榜数据完全够用。第三个是主题系统：除了经典配色，计划加入暗黑主题和像素风主题，点击主题卡片一键切换棋盘和数字的样式，这块正在做。
另外，我还打算抽时间把这套扫雷逻辑封装成一个独立的Flutter包，发布到pub.dev上。原因是现在网上开源的扫雷实现要么是针对Web的，要么是Android原生的，真正适配OpenHarmony的示例代码几乎没有。如果能把核心逻辑和UI组件分离做成插件，以后有人要在OpenHarmony上做游戏集合类App，就可以直接拿来用了，这也是我们做开源社区的一种回馈方式。
最后说一个经验之谈：跨平台开发适配新系统，最大的坑不是你写的业务代码有多难，而是你不敢动手试。Flutter for OpenHarmony确实还有不少不完善的地方，但扫雷这个项目的实践说明，只要不触及底层渲染或者复杂原生交互，纯Flutter逻辑的应用迁过去并没有想象的那么可怕。尤其是数字显示、网格布局、状态管理这些基础能力，一次开发，两边渲染，投入产出比非常可观。如果你也在考虑在OpenHarmony上做点什么，建议先从这种中小型的工具类或游戏类应用入手，踩坑成本低，收获的经验却非常实在。
