CustomPainter 这个名字玩过 Flutter 的人多少都听过但真正把它用在游戏画面渲染上、还跑在 OpenHarmony 设备上的人可能没那么多。这篇文章想跟你分享的就是这么一件事用 Flutter 的 CustomPainter 在 OpenHarmony 上做一套轻量级 2D 游戏画面渲染方案。不是那种重量级游戏引擎就是自己可控、能一帧帧画出来的那种。我会把 CustomPainter 的核心机制、游戏循环的搭建、粒子系统的实现、常见性能坑以及 OpenHarmony 平台上特有的适配问题都拆开讲。如果你正打算在 OpenHarmony 设备上做点带画面的东西或者想把已有的 Flutter 小游戏移植过去这篇文章应该能省你不少时间。文章里所有代码都是可跑的思路也是我在实际项目中验证过的。1. 为什么偏要在 OpenHarmony 上用 Flutter 做游戏渲染先说个很多人会问的问题OpenHarmony 自己不是有 ArkTS 和 ArkUI 吗Canvas 能力也不差为什么还要绕一圈用 Flutter 的 CustomPainter1.1 从“跨端复用”到“渲染自控”的需求变化大多数团队接触 OpenHarmony不是因为它生态丰富而是因为业务要覆盖这个平台。这时候最现实的问题是Android 上那套 Flutter 游戏代码能不能直接搬过来答案在绝大多数情况下是“能”。Flutter 的渲染层在 OpenHarmony 适配版里走的是自绘引擎不依赖系统原生控件所以你用 CustomPainter 画的每一个圆、每一条路径在 Android 和 OpenHarmony 上的表现几乎一致。这一点对游戏开发来说太关键了——游戏画面最怕的就是“换个平台渲染效果就变了”。另一个原因是开发效率。ArkUI 的 Canvas 组件我也试过写起来并不复杂但如果你已经有一套 Flutter 的游戏逻辑、资源管理和状态管理方案重新用 ArkTS 写一遍的成本远高于直接做 Flutter 适配。更别说 Flutter 的热重载在调试游戏这种高频改动场景下有多好用——改个粒子的颜色、调一下碰撞的力度秒级看到效果这在原生开发里是奢侈的。1.2 ArkTS 与 Flutter 的选型边界我见过不少团队在 ArkTS 和 Flutter 之间纠结这里给你一个我自己的判断标准如果项目是纯 OpenHarmony 单平台、以系统能力集成为主、团队原生开发经验丰富那 ArkTS 更顺。如果项目需要覆盖多端、已经有 Flutter 技术积累、或者游戏逻辑会持续迭代那 Flutter 的性价比明显更高。这个例子不是说他俩谁比谁强而是告诉大家选 Flutter 做 OpenHarmony 游戏渲染核心驱动力是“代码复用”和“渲染一致性”。OpenHarmony 系统本身用什么语言编写其实和你上层开发关系不大——你只需要知道你的 Flutter 代码最终是通过适配层的自绘引擎把画面呈现出来的这点足够了。2. CustomPainter 的核心机制拆解画布、画笔与重绘协议你只有彻底理解了 CustomPainter 的原理才能在游戏渲染里用好它。它不是一个“组件”而是一套绘制协议。2.1 paint、Canvas、Size 三者的实际关系CustomPainter 的核心就是你必须实现 paint(Canvas canvas, Size size) 这个方法。系统会在需要绘制时把一块画布Canvas和一个尺寸Size交给你。Size 就是这块画布的逻辑尺寸比如 360x640单位是逻辑像素不是物理像素。Canvas 则是你所有绘制操作的入口——画圆、画矩形、画路径、画图片全走它。很多人第一次写 CustomPainter 会犯一个错误在 paint 方法里写死坐标。比如画一个直径 100 的球就写 canvas.drawCircle(Offset(10, 10), 50, paint)。这在固定尺寸下没问题但游戏画面往往要适配不同分辨率的设备。正确的做法是以 Size 为基准计算相对位置比如 Offset(size.width / 2, size.height / 2) 表示画布中心。这就引出了一个关键认知paint 方法每次被调用都有可能是不同的 Size。比如设备旋转、窗口尺寸变化系统都会重新走绘制流程。所以你在 paint 方法里一定要有“按当前 Size 重新计算布局”的能力而不是假设尺寸不变。游戏里那些“位置偏移”“缩放比例”的逻辑也建议放在 paint 方法之外算好paint 只负责把当前状态画出来。2.2 shouldRepaint聪明的重绘开关CustomPainter 另一个必须实现的方法是 shouldRepaint(covariant CustomPainter oldDelegate)它决定了“这个 painter 的新实例和旧实例相比是否需要重绘”。返回 true 就重绘返回 false 就跳过。这个方法的本质是性能协议。如果每次 build 你都创建新的 CustomPainter 实例但画的内容其实没变化返回 false 就能让 Flutter 跳过重绘省下宝贵的帧预算。游戏场景里画面几乎每帧都在变所以通常直接返回 true但有一个特例当游戏暂停或切换到后台时如果你能把“画面未变化”的状态表达出来返回 false 就能让 GPU 完全不干活省电效果立竿见影。我自己的做法是维护一个 dirty 标志位游戏状态变化时就置 trueshouldRepaint 直接返回旧 painter 的 dirty 值。这样既能在游戏中保持满帧重绘又能在静止画面时自动休眠。3. 游戏画面渲染实战从零搭一个粒子系统 Demo理论说到这儿直接进入正题。我用“烟花粒子系统”作为例子——它麻雀虽小五脏俱全涵盖了游戏渲染的全部核心环节帧循环、动画插值、粒子生命周期管理、Canvas 绘制、性能优化。而且视觉效果好调试起来成就感强。3.1 项目初始化与 OpenHarmony 环境适配先说明一下环境。OpenHarmony 上的 Flutter 支持走的是社区维护的适配分支。创建 Flutter 项目的时候你需要确保 SDK 路径指向 OpenHarmony 适配版然后用 flutter create 生成项目平台列表里就能看到 ohos 目录。要注意几个点请自行检查 Flutter 版本与 OpenHarmony SDK 的兼容关系版本不对会直接导致跑不起来。首次在 OpenHarmony 真机运行时建议先用自带模板项目跑通排除开发环境问题后再加入业务代码。如果遇到新建项目后跑不起来的情况检查思路确认环境变量是否正确、SDK 路径是否有效、设备是否开启了开发者模式。80% 的启动失败都是这三件事。3.2 游戏循环架构用 Ticker 驱动每一帧Flutter 里驱动逐帧更新的最佳选择是 Ticker它由 SchedulerBinding 管理每一帧都会回调一次传入当前帧的时间戳。和 AnimationController 相比Ticker 更轻量没有 Animation 的插值语义更适合纯粹的游戏循环。以下是游戏循环的核心骨架class GameEngine extends ChangeNotifier { GameEngine() { _ticker createTicker(_onTick); _ticker.start(); } late final Ticker _ticker; final ListParticle _particles []; Duration _lastFrameTime Duration.zero; bool _isRunning true; void _onTick(Duration timestamp) { if (_lastFrameTime Duration.zero) { _lastFrameTime timestamp; return; } final dtMs (timestamp - _lastFrameTime).inMicroseconds / 1000.0; _lastFrameTime timestamp; if (_isRunning) { _update(dtMs); notifyListeners(); } } void _update(double dtMs) { // 更新粒子位置、速度、生命周期 for (final particle in _particles) { particle.update(dtMs); } _particles.removeWhere((p) p.isDead); } override void dispose() { _ticker.dispose(); super.dispose(); } }这里有个细节dtMs 是毫秒为单位的时间增量所有物理运算都基于它。为什么不用随机数或固定步长因为不同设备帧率不一样用真实时间差才能保证粒子速度和位移在不同刷新率下表现一致。你换成 120Hz 的设备粒子不会突然变快这是游戏“帧率无关”的基本功。3.3 CustomPainter 渲染端代码按状态画每一帧有了游戏引擎渲染端就是把状态画出来。以下是这个 Demo 中的 CustomPainter 实现class ParticlePainter extends CustomPainter { ParticlePainter({required this.particles, required this.dirty}); final ListParticle particles; final bool dirty; override void paint(Canvas canvas, Size size) { final paint Paint() ..style PaintingStyle.fill ..isAntiAlias true; for (final particle in particles) { // 用生命周期比例计算透明度 final alpha (1.0 - particle.life / particle.maxLife).clamp(0.0, 1.0); paint.color particle.color.withOpacity(alpha); canvas.drawCircle( particle.position, particle.radius, paint, ); } } override bool shouldRepaint(covariant ParticlePainter oldDelegate) { return dirty || oldDelegate.dirty; } }绘制逻辑简洁且高效但这里有三个“绝对不要做的事”不要在 paint 方法里 new 大量的 Paint 对象。Paint 的构建有开销放在循环里逐帧创建会显著拉低帧率。正确做法是把 Paint 提到外面复用只改颜色这种轻量属性。不要用 saveLayer 做全局透明度或裁剪。saveLayer 会创建离屏缓冲对 GPU 开销很大小游戏里能避开就避开。粒子透明效果直接画 Circle 就行。不要在 paint 里做碰撞检测或任何逻辑运算。paint 方法属于渲染层它应当只负责“把状态画出来”任何状态计算都应该在帧循环里完成放在 paint 里会导致渲染卡顿难排查。3.4 在界面上组合 CustomPaint 与游戏引擎渲染端和引擎端都有了还差一个把它们接起来的界面。用 CustomPaint 组件包住 painter再用 ListenableBuilder 监听引擎状态变化即可。结合 Real RepaintBoundary 隔离绘制区域避免整个页面跟着重绘。你可以用自己熟悉的组件通信方式Flutter 里常见的 provider 或者 ChangeNotifier 都行。我的建议是轻量场景直接用 ListenableBuilder不额外引入状态管理库少一层依赖少一层坑。class GameScreen extends StatefulWidget { const GameScreen({super.key}); override StateGameScreen createState() _GameScreenState(); } class _GameScreenState extends StateGameScreen { final GameEngine _engine GameEngine(); override void dispose() { _engine.dispose(); super.dispose(); } override Widget build(BuildContext context) { return Scaffold( backgroundColor: Colors.black, body: RepaintBoundary( child: ListenableBuilder( listenable: _engine, builder: (context, _) { return CustomPaint( painter: ParticlePainter( particles: _engine.particles, dirty: true, ), size: Size.infinite, ); }, ), ), ); } }这套架构已经是一个完整的游戏渲染循环。你后续要做弹跳小球、飞机大战、或者简单的跑酷游戏都沿用同样的套路GameEngine 管状态和更新CustomPainter 管绘制StatefulWidget 做桥接。4. 性能优化从 30 帧到 60 帧的实战调优CustomPainter 游戏渲染的性能是个大话题我把自己踩过的坑和经验按优先级整理一遍。4.1 绘制开销的黄金法则能少画就少画CustomPainter 的性能问题九成出在“画了不该画的东西”。以下几条是排查性能问题时最先该怀疑的不可见的粒子还在绘制。粒子超过生命周期还没被移除或者离开屏幕区域还在画这是最常见的开销浪费。解决办法是移出屏幕的粒子直接标记为死亡或者用视口裁剪判断。渐变阴影和遮罩处理过度。Flutter 的 MaskFilter、ImageShader、saveLayer 都是重量级操作。我见过有人用 MaskFilter.blur 做粒子光晕帧率直接掉一半。有条件就用多层半透明圆叠加模拟不要上模糊。每帧全量重建 Paint。前面说过paint 方法里不要再做 Paint 构建尽量放到 painter 的构造函数里或者作为 painter 类的字段。调整之后建议用 DevTools 的 Performance 面板看每一帧的耗时。如果 UI 线程的 build 和 layout 时间都很短但 Raster 线程耗时高问题大概率出在 CustomPainter 的绘制命令上。Raster 线程的耗时曲线就是你画布的“性能晴雨表”。4.2 物理分辨率与逻辑像素清晰度的关键OpenHarmony 设备的屏幕密度千差万别有的 2 倍有的 3 倍甚至更高。Flutter 的逻辑像素会自动乘以设备像素比devicePixelRatio但如果你把 ui.Image 这种位图资源直接画出来要考虑贴合实际清晰度要求。表现就是字和图标都清楚但游戏画面里的小元素边缘发虚。我的解决方案是所有游戏内位图资源都按目标设备最大像素比加载两份1x 和 2x在代码里根据 MediaQuery.devicePixelRatio 选择。矢量形状则完全不需要担心这个问题这就是能用 Canvas 画的尽量用 Canvas 画的原因。4.3 Ticker 的暂停与销毁生命周期管理游戏切后台、页面压栈Ticker 如果还在一帧帧跑纯属浪费资源。Android 上走的是 WidgetsBindingObserver 的生命周期回调在 OpenHarmony 上同样适用你要在 didChangeAppLifecycleState 里控制 Ticker 的停止与恢复。切忌在 dispose 里忘记销毁 Ticker一旦泄露页面关闭后 Ticker 还在驱动重绘结果就是内存持续上涨和莫名其妙的崩溃。我这里直接给出一个现在正在用的安全模板class GameEngine extends ChangeNotifier with WidgetsBindingObserver { override void didChangeAppLifecycleState(AppLifecycleState state) { super.didChangeAppLifecycleState(state); if (state AppLifecycleState.resumed) { _ticker.start(); } else { _ticker.stop(); } } }注意 WidgetsBindingObserver 需要你手动 addObserver页面销毁时要记得 removeObserver这套组合是生命周期管理的标准动作。5. 常见问题与排查技巧实录拿这套方案在 OpenHarmony 设备上跑有几个问题几乎是必现的提前给你打预防针。5.1 图片资源加载不出来或白屏CustomPainter 支持 drawImageRect 和 drawAtlas 画位图但加载图片是异步的。很多人踩的坑是在 paint 方法里同步加载图片而图片还没加载完就开始绘制结果白屏。正确的加载方式是通过 instantiateImageCodec 或 rootBundle.load 获取 ByteData再异步解码成 ui.Image。图片解码完成后需要把 painter 标记为 dirty 触发重绘不能指望系统自动感知图片加载完成。在游戏初始化阶段提前预热所有图片资源这是最稳妥的方案。5.2 粒子数量多了之后明显掉帧手机上 Particle 数量超过 500 个时CustomPainter 纯 drawCircle 的性能会开始下降。这时候需要升级渲染方式把同类型、同颜色的粒子合并成一条 drawPoints 命令或者用 drawVertices 批量绘制。Flutter 的单条绘制命令开销远低于逐粒子调用把 500 次 drawCircle 合并成 5 次 drawPoints帧率立竿见影。如果你需要更复杂的精灵动画可以考虑用 Canvas.drawAtlas 一次性绘制多张图片这也是 Flutter 官方游戏渲染的常见优化路径。5.3 “Flutter 新建项目后跑不起来”的综合排查方案这个问题热搜榜上始终有它。如果你用的是 OpenHarmony 适配版 Flutter SDK跑不起来大概率是以下几类原因按顺序排查系统环境变量里 Flutter 路径是否真的有 SDK运行 flutter doctor 确认版本。项目目录下是否有 ohos 平台目录以及用的 SDK 版本是否与项目创建时匹配。真机连接后是否授权调试OpenHarmony 设备上这一步经常因为用户没手动弹窗而失败。如果控制台报 Gradle 相关错误先检查网络和 Gradle 仓库配置特殊网络环境需要配置镜像源。遇到问题别乱改代码先跑一个官方模板项目验证基础链路是否通这是最快的判断方法。5.4 性能问题排查看 Raster 而不是 UIFlutter 性能排查有个经典误区UI 线程不卡就认为页面流畅。实际上很多 CustomPainter 的卡顿发生在 Raster光栅化线程UI 线程耗时可能只有 1msRaster 线程却占了 30ms。Debug 模式跑起来很流畅Release 打包后反而掉帧这种反差多半就是 Raster 线程的绘制命令太重。用 Profile 模式跑真机DevTools 的帧时间分析里能直观看到 UI 和 Raster 分别耗时多少。像 saveLayer、MaskFilter、复杂的 Path 运算都是 Raster 耗时大户遇到就砍掉或者换成低开销实现。哪怕只是把 isAntiAlias 在不需要的地方关掉都可能带来稳定的性能提升。6. 这套方案还能往哪个方向扩展CustomPainter 不是只能做粒子系统。我目前在这个架构上向外扩展了几个方向实践下来都挺顺畅。6.1 接入精灵动画与图集渲染游戏里的角色动起来需要逐帧切换图片或按帧动画播放序列帧。CustomPainter 里可以用 drawImageRect 从图集中截取指定区域绘制配合 AnimationController 或游戏时间戳驱动帧序号就能实现高效的精灵动画。再进阶一步用 drawAtlas 可以把多个角色一次性绘制适合大量同屏精灵的场景。这里有一个性能关键提前把图集解码为 ui.Image并在游戏循环中只更新帧序号不要每次重新解码。我在某模拟项目里用这套方式实现了 100 个同屏精灵的流畅动画开满 60Hz 完全不喘气。6.2 碰撞检测的可视化调试碰撞检测不在 CustomPainter 的责任范围内但调试碰撞体时 CustomPainter 却是个完美的可视化工具。你可以把碰撞盒、碰撞圆、物理引擎里的刚体轮廓全部用半透明色画出来通过一个 debug painter 叠加在游戏画面上。正常游戏里这个 painter 关掉调试时打开看到的就是实时的物理碰撞可视化。常见的做法是给游戏引擎维护一份 debugShapes 列表每帧把需要可视化的形状塞进去painter 遍历绘制。这样你能直接看到碰撞体和视觉重影是否一致比用断点看数据高效太多。6.3 接入游戏状态管理从 setState 到可控的状态机小 Demo 用 ChangeNotifier 加 ListenableBuilder 足够但游戏一旦有了菜单、战斗、结算多种场景建议引入轻量级状态机。状态机的好处是每一帧你明确知道当前处于哪个阶段CustomPainter 也能根据状态切换绘制层级。比如菜单状态下只绘制 UI战斗状态下才绘制粒子特效和角色。用 provider 管理游戏状态在 Flutter 社区已经很成熟你把你自定义的 GameEngine 挂在 provider 顶层然后页面用 context.watch 监听引擎变化跟之前纯 ListenableBuilder 的思维模型完全一致只是多了一层依赖注入的壳。这很适合游戏模块持续变大的场景建议你在架构设计初期就定好这一层抽象不要等代码写飞了再重构。6.4 OpenHarmony 摄像头画面联动Hot 词里有“openharmony camera”这也是一条可走通的路。CustomPainter 的绘制结果可以叠加在 Camera 预览之上做法是让相机预览画面作为 CustomPaint 的 child或者通过 Texture 控件把相机帧渲染为纹理CustomPaint 再画一层粒子或滤镜效果。这样就能在 OpenHarmony 上做 AR 滤镜类的特效开发核心还是我们前面讲的那套刷新和渲染协议只是多了一个数据源。我实验下来的效果是相机帧经 Texture 渲染后叠加 CustomPainter 粒子层帧率基本不受影响前提是粒子层保持轻量。如果你的游戏需要根据摄像头画面交互这个方向很值得探索。7. 现在动手最小可用版本的实现清单讲了这么多你需要的最小可用版本按下面的清单一步步来两小时内就能跑出烟花效果。准备环境安装 OpenHarmony 适配版 Flutter SDK用 flutter doctor 检查合格创建 Flutter 项目建议项目名不要带大写字母否则在 ohos 平台可能会踩编译坑。写一个 Particle 类包含 position、velocity、life、maxLife、radius、color以及 update(double dtMs) 方法坐标按屏幕 Size 更新。写一个 GameEngine 继承 ChangeNotifier维护粒子列表。每帧用 Ticker 驱动更新粒子位置和生命周期然后调用 notifyListeners。写一个 ParticlePainter 继承 CustomPainter把 GameEngine 里的粒子列表画成半透明圆shouldRepaint 返回 dirty 标志代表进入重绘状态。把 CustomPaint 放进 RepaintBoundary 里用 ListenableBuilder 监听 GameEngine构建出完整页面。真机运行验证帧率和性能根据前面性能优化的清单逐条检查。这个清单再简化一下就是引擎管状态、Painter 管绘制、Ticker 管节奏。这三件事做好任何 2D 小游戏画面都能拿 CustomPainter 搞定。我在实际项目中跑这套方案的过程中踩过最大的坑是设备适配问题——不是代码问题而是不同 OpenHarmony 设备的屏幕刷新率差异导致游戏速度表现不一致。多亏最后统一用了 dtMs 驱动的更新逻辑这个问题才彻底解决。那些看起来“无所谓”的时间参数往往是游戏体验差异的真正来源。如果你也想在 OpenHarmony 上做点视觉交互的东西从 CustomPainter 入手吧。它是 Flutter 渲染最底层的骨骼先摸透它之后再上游戏引擎、特效框架心里都会稳得多。请在确保无网络连接风险的基础环境中使用切勿在关键业务场景中直接复制以上代码先充分测试再上线。