Flutter应用移植OpenHarmony：错误处理与异常管理实战指南

做开发最怕的不是报错，是错得莫名其妙、复现不了、日志还没有。这阵子我把一个 Flutter 写的视力保护提醒 App 完整跑到了 OpenHarmony 设备上，功能本身不复杂——定时提醒用户休息眼睛、统计用眼时长、强制弹窗打断——真正折磨人的是适配过程中那一堆错误处理和异常管理的问题。标题里“错误处理与异常管理”这几个字，看着像是项目收尾时补文档的章节，实际做下来才知道，这是整个 Flutter for OpenHarmony 移植过程里最考验耐心的一环。

这个 App 的核心场景很直白：用户在电脑前或者平板上连续工作一段时间，应用通过前台计时判断用眼时长，到点就发送通知提醒休息，如果用户迟迟不休息，就弹全屏遮罩强制打断。我最初在 Android 上写得顺风顺水，等决策要移植到 OpenHarmony 设备时，麻烦才开始显现。Dart 层的异常捕获逻辑、平台通道的调用失败、后台任务的调度被系统杀掉、通知权限被拒绝后的静默失效……每个都能让一个看起来没问题的 App 在真机上表现得像个坏掉的产品。

写这篇东西，是想把这套移植过程中的错误处理和异常管理方案完整记录下来。项目代码是在某内部实验平台上跑的，属于一个模拟的学习项目，设备是某国产开发板，系统版本是 OpenHarmony 的某个标准系统版本。内容适合两类人看：一是正准备把自己的 Flutter 应用往 OpenHarmony 上搬的移动开发者，二是 App 功能不复杂但想提前把稳定性做扎实的新手。我会把整个异常处理的架构思路、关键代码、还有排查实录摊开来讲清楚，确保你读完能直接拿这套思路去套自己的项目。

1. 项目设计与错误处理思路拆解

1.1 视力提醒 App 的核心逻辑与功能模块

先把这个 App 的底交代清楚。视力保护提醒，核心是两件事：计时和提醒。计时负责统计用户连续用眼时长，提醒负责在合适的时间用合适的方式打断用户。

从代码模块来划分，整个 App 可以拆成四块：

• 前台计时器模块：利用 Dart 层的 Timer 周期性刷新状态，记录已用眼时长，这是最核心的状态源。
• 后台调度模块：利用 OpenHarmony 平台的闹钟或任务调度能力，在应用被切到后台后仍然能触发计时回调，这也是移植过程中最容易出错的地方。
• 通知与强提醒模块：通过平台能力发通知、弹全屏遮罩，涉及权限申请和异常处理。
• 统计与状态持久化模块：把每次休息记录、用眼时长写入本地存储，这里要处理文件读写异常和数据损坏的问题。

这套结构在 Android 上没有任何稀奇之处，但在 OpenHarmony 上，问题来了。OpenHarmony 的 Flutter 支持目前是通过社区维护的 flutter_flutter 和 OpenHarmony 适配层完成的，第三方插件的生态远不如 Android 成熟。很多在 Android 上直接调用的插件，在 OpenHarmony 上要么没有实现，要么实现得不完整。所以我在设计时做了个取舍：能用 Flutter 原生 Dart 实现的，绝不上插件；必须调平台能力的，全部走 MethodChannel 自研封装，不走第三方插件。这个决策直接影响了后面整个错误处理架构的形态。

1.2 为什么在 OpenHarmony 上必须提前设计错误处理架构

在 Android 上写 Flutter 应用，错误处理经常是散装的：这里 catch 一下，那里抛个异常，项目能跑就没人管。但在 OpenHarmony 上这套行不通，原因我总结成三条。

第一，平台通道失败率远高于 Android。同样是调用通知服务，Android 的插件经过多年打磨，各种边界情况都被处理过。而 OpenHarmony 的 Flutter 平台通道实现还在快速演进期，MethodChannel 调用可能因为系统服务未就绪、参数格式不兼容、甚至适配层的 bug 而失败。这些异常在开发机上不一定复现，在真机上却可能频繁出现。

第二，很多错误不是 Dart 层能捕捉的。举个例子，你在 Dart 层调用平台通道去注册一个后台任务，平台侧已经崩溃了，Dart 层拿到的只是一个笼统的 PlatformException，原始的堆栈和错误原因都在原生侧，如果不做双层的错误采集，后期排查就是大海捞针。

第三，视力提醒这类应用对稳定性极其敏感。用户对“到点不提醒”的容忍度为零。一次定时器失效、一次通知被吞，用户就会认定这是个坏应用。这就要求所有关键路径必须有失败的兜底策略：主方案挂了，备方案要顶上；备方案也挂了，至少要给用户一个可见的错误提示，而不是静默失败。

所以我想清楚了一件事：错误处理不是项目做完之后补的，而是从一开始就要铺进去的地基。我把这套设计原则叫做“三不原则”：关键路径不允许静默失败、平台异常不允许裸奔、用户操作不允许无反馈。后面所有代码和排查思路，都是围绕这三条展开的。

1.3 错误分类与异常处理总体框架

动手写代码之前，我先给整个项目的异常做了个分类。没有分类的异常管理，写到最后必然是一团乱麻。我把异常分成三个层次，对应三层代码。

Dart 层异常：包括 Timer 回调里的逻辑错误、状态机的不合法转换、json 解析失败、本地存储读写错误。这类异常的特点是发生在 Flutter 框架内部，可以在 Dart 层直接用 try/catch 和 runZonedGuarded 捕获，处理手段最直接。

Flutter-Framework 层异常：包括 Widget 构建时的异常、布局溢出、异步任务的 unhandled error。这类异常如果不在全局层面兜底，会导致 Flutter 引擎直接卡死或结束运行，用户体验就是“白屏”或“闪退”。需要用 PlatformDispatcher.instance.onError 和 FlutterError.onError 双管齐下。

OpenHarmony 平台通道层异常：包括 MethodCall 无法被处理、返回结果格式不合法、系统权限被拒绝、后台任务调度失败。这类异常的特点是部分信息在原生侧，Dart 层只能拿到经过序列化的错误码。我在原生侧（ArkTS 代码）也做了统一的错误处理和日志上报，和 Dart 层的日志拼接在一起才能还原完整的调用链。

这三个层次相互独立又相互影响。比如后台调度失败，是 Dart 层正确地调用了平台通道，但平台的实现栈抛了异常，异常既需要被 Dart 层捕获并转换为用户可理解的错误提示，也需要被原生侧的 catch 块记录下来供排查。所以我建了一套统一的错误码体系，方便三层日志对齐。

这套体系里，我用了一个自定义的 AppException 异常类型，携带错误码、错误源、用户提示和原始异常四个字段。整个 App 里不允许在 UI 层直接 catch 裸异常，凡是需要向上抛的，都必须包装成 AppException。这样做有两个好处：一是 UI 层拿到异常后可以直接读取 userMessage 字段用于展示，不需要自己猜；二是日志层可以根据错误码做归类统计，知道哪些错误是高频的、哪些是偶发的。

2. 错误处理核心细节与实操要点

2.1 全局异常捕获：Dart 层的最后一道防线

全局异常捕获是错误管理的地基，它的作用是兜住所有“没被兜住”的异常。Flutter 应用有两个关键的全局异常入口，一个是同步/异步代码里的未捕获异常，走的是 PlatformDispatcher.instance.onError；另一个是 Flutter 引擎在构建和渲染时抛出的异常，走的是 FlutterError.onError。

很多人只处理了第一个，忽略了第二个，结果是一遇到布局错误就白屏。我的做法是在 main() 开头就同时挂上两个钩子，并且把所有异常都汇入同一个上报通道。

dart复制void main() {
  // 处理 Dart 层的未捕获异常，包括异步任务的异常
  PlatformDispatcher.instance.onError = (Object error, StackTrace stack) {
    final appException = AppExceptionWrapper.wrap(error, stack: stack);
    ErrorReporter.report(appException, source: 'dart-global');
    return true; // 返回 true 表示异常已处理，防止 Flutter 引擎直接终止
  };

  // 处理 Flutter 框架层的异常，如 build 期间的异常
  FlutterError.onError = (FlutterErrorDetails details) {
    FlutterError.presentError(details);
    ErrorReporter.report(
      AppExceptionWrapper.wrap(details.exception, stack: details.stack),
      source: 'flutter-framework',
    );
  };

  runApp(const VisionGuardApp());
}

这个设计里有两个细节值得注意。

第一个细节是 PlatformDispatcher.instance.onError 回调返回值的含义。返回 true 表示“这个异常我已经处理了”，Flutter 引擎会继续运行；返回 false 才会终止。很多应用崩溃后的日志只能看到引擎报错，看不到应用自己的异常信息，就是因为这里没处理好。我全部返回 true，但内部会把异常上报到本地日志和展示页面，保证用户能看到错误提示，而不是直接闪退。

第二个细节是把框架异常和 Dart 异常分开处理。FlutterError.onError 里先调用 FlutterError.presentError(details)，让框架的默认展示逻辑正常工作，再自己上报。不调用 presentError 的话，控制台会静默，后期调试时缺失关键信息。

实际跑下来，这套全局兜底在 OpenHarmony 的调试阶段帮我挡下了至少六七个隐蔽的异常。最典型的是一次在设置页构建时，某个图片资源在 OpenHarmony 上加载失败，导致 build 方法抛了异常。如果没有 FlutterError.onError 兜住，整个页面会直接显示为空白，用户完全不知道发生了什么。兜住之后，我至少能在日志里看到报错，页面也能弹出“加载失败”的遮罩。

2.2 异步异常捕获：Timer 和 Future 是坑的重灾区

视力提醒 App 里面最要命的是 Timer。Timer 的回调是异步执行的，你没法用普通的 try/catch 把回调体包住就万事大吉——因为 Timer 的创建和回调的执行不在同一个调用栈里。如果你在 Timer 回调里抛了异常，且没有在回调内单独捕捉，这个异常会直接冒泡到全局 PlatformDispatcher.instance.onError，虽然是能兜住，但问题在于上下文信息不够：你不知道这个异常是哪个 Timer 抛出来的。

我在项目里做了一个小封装，给所有敏感 Timer 加了一层保护壳。

dart复制class SafeTimer {
  Timer? _timer;

  void start(Duration duration, void Function() callback) {
    _timer?.cancel();
    _timer = Timer(duration, () {
      try {
        callback();
      } catch (e, s) {
        ErrorReporter.report(
          AppExceptionWrapper.wrap(e, stack: s, source: 'safe-timer'),
        );
        // 额外处理：如果回调失败，根据策略决定是否重试
      }
    });
  }

  void cancel() {
    _timer?.cancel();
    _timer = null;
  }
}

为什么不做成把 catch 逻辑直接写在每个业务回调里？因为写多了人的惰性会占上风，总有一个你漏掉。做一个统一的安全壳，至少保证业务层不用重复写 try/catch，错误也都有统一的 source 标记。

另外一个容易踩的坑是 async 方法的异常。Dart 的 async 方法如果内部抛异常，且调用方没有 await，那么这个异常会成为 unhandled async error。最稳妥也是最容易忽略的做法是：所有 async 方法内部都要自带 try/catch，或者明确返回 Result 类型，绝不让 async 函数凭空向外抛异常。

我还处理了 Future 等待超时的问题。比如在启动时，App 要和平台通道通信，注册后台任务调度回调。如果平台侧迟迟没有响应，Future 就会一直挂着，用户看到的界面就会卡在启动页。针对这种情况，我封装了一个 withTimeout 方法，给所有平台通道调用加了超时保护。

dart复制Future<T> withTimeout<T>(Future<T> future, {Duration timeout = const Duration(seconds: 3)}) async {
  try {
    return await future.timeout(timeout);
  } on TimeoutException {
    throw AppExceptionWrapper.wrap(
      TimeoutException('平台通道调用超时'),
      source: 'platform-channel',
    );
  }
}

这里要提醒一下，OpenHarmony 上的平台通道调用，首次调用的初始化耗时通常比 Android 略长。我把默认超时设置成了三秒，实测在开发板上基本能在两秒内返回。如果你设备性能差一点，可以放宽到五秒，但不能再长，再长用户就感知到卡顿了。

2.3 平台通道异常处理：与原生侧通信的容错设计

我因为不信任第三方插件的 OpenHarmony 兼容性，所以所有平台能力调用全部走自研的 MethodChannel。这样一来，平台通道的异常管理就得自己写。平台通道的错误有两种，必须分开对待。

第一种是通道不存在。比如你调用了 MethodChannel('vision_guard/timer')，但原生侧还没注册这个 channel。这种会直接抛出 MissingPluginException，在 Android 上是运行时异常，在 OpenHarmony 上同样会以异常形式抛出。对这种错误，我给每个 channel 做了一个存活检查：在 App 启动时先调用一个 ping 方法，确认通道可达，如果 ping 不通，就自动切到降级模式，把“原生调度”降级成“纯 Dart 前台计时”。

第二种是业务调用的业务失败。比如注册后台任务时权限被系统拒绝，原生侧会返回一个包含错误码、错误信息、详细参数的 PlatformException。我在 Dart 侧封装了一层 channel service，把这些异常统一转换成 AppException。

dart复制class VisionGuardChannelService {
  static const MethodChannel _channel = MethodChannel('vision_guard/core');

  Future<bool> registerWorkScheduler() async {
    try {
      final result = await _channel.invokeMethod<bool>('registerWorkScheduler');
      return result ?? false;
    } on PlatformException catch (e) {
      throw AppExceptionWrapper.platformError(
        code: e.code,
        message: e.message ?? '未知平台错误',
        details: e.details,
      );
    } on MissingPluginException catch (e) {
      throw AppExceptionWrapper.platformError(
        code: 'missing-plugin',
        message: '平台通道不可用，请检查原生侧注册',
        details: e,
      );
    }
  }
}

在原生侧（用 ArkTS 编写），我也做了配套的错误处理。ArkTS 侧调用系统能力失败时，同样有自己的一套 error code。我建了一个映射表，把 ArkTS 的错误码映射成 Dart 侧统一的错误码，确保两边看到的错误语义一致。比如 OpenHarmony 上常见的 201 错误码代表权限校验失败，我把它映射成 permission_denied；401 代表参数错误，映射成 invalid_arguments。

这个映射表是整个错误处理体系里最花时间的工作，因为要对着系统 API 文档逐个核对错误码。做完了之后，Dart 侧排查问题的效率提高了很多，看到错误码就知道是权限问题还是参数问题，不用每次去原生侧 Log 里翻了。

2.4 业务层异常管理：状态机与降级策略

业务层的异常管理，核心是两件事：防止状态错乱和提供降级路径。

视力提醒 App 的核心状态是一个状态机：空闲 -> 用眼中 -> 警告 -> 强制休息。任何一次异常中断（比如 Timer 被取消、通知发送失败）都不能让状态机卡死在某个状态里。我的做法是给状态机的每一个流转操作穿上事务性保护：先快照当前状态，执行操作，如果操作失败则恢复快照并标记异常。

dart复制class EyeGuardStateMachine {
  EyeGuardState _state = EyeGuardState.idle;
  EyeGuardState _lastSnapshot = EyeGuardState.idle;

  void transitionTo(EyeGuardState target) {
    _lastSnapshot = _state;
    try {
      _validateTransition(_state, target);
      _state = target;
      // 状态变更后的副作用，比如重置 Timer
      _onStateChanged(_state);
    } catch (e) {
      // 回滚，保证状态机不卡死
      _state = _lastSnapshot;
      ErrorReporter.report(AppExceptionWrapper.wrap(e, source: 'state-machine'));
    }
  }
}

这个回滚机制看起来简单，但它解决了一个重要问题：强提醒弹窗的展示必须在状态切换之后立刻执行。如果弹窗展示抛异常（比如页面上下文已经销毁），状态机不能停留在“警告”状态，否则下一次计时到了，界面上的提示逻辑会错乱。

降级策略是这套体系里最实用的部分。我在设计时给每个关键功能都准备了至少一个降级路径，规则很简单，当主路径失败时，不能没有下一步动作。

以休息提醒为例。主路径是：Dart 层 Timer 触发 -> 调平台通道发系统通知 -> 弹全屏遮罩。如果平台通道发通知失败，降级路径是：应用内部直接弹一个不可跳过的全屏 Dialog，同时用声音震动提醒。也就是说，即使没有系统通知，用户依然会被打断。如果全屏 Dialog 也失败（比如页面被系统回收），最后一道防线是：把“需要休息”标志写入本地存储，下次打开 App 时读取并提示。这套多级降级保证了功能的核心价值永远不落空。

这个设计在真实运行中非常管用。有几次开发板上的通知服务莫名不可用，通知渠道失败，按旧方案用户就漏了一次休息提醒。有了全屏 Dialog 兜底后，虽然用户看到的是应用内弹窗而不是系统通知，但休息提醒这件事本身完成了。要记住，视力保护这类应用的业务目标是“提醒成功”，而不是“某种提醒方式的成功”。

3. 实操过程：从零搭建错误处理与异常管理体系

3.1 第一步：先把全局错误上报管道搭起来

整个体系的搭建，我的顺序是先把“错误上报管道”跑通，再往里填具体的业务逻辑。原因是如果在业务代码里到处加了捕获逻辑，但上报管道是空的，等于所有捕获都白做。

上报管道我分成两层：一层是本地落盘，一层是控制台打印。

dart复制class ErrorReporter {
  static final List<AppException> _pending = [];

  static void report(AppException exception, {required String source}) {
    _pending.add(exception);
    _dumpToLocal(exception, source);
    debugPrint('[ErrorReport][$source] ${exception.code} ${exception.userMessage}');
  }

  static Future<void> _dumpToLocal(AppException exception, String source) async {
    try {
      final file = await _getLogFile();
      final line = '[${DateTime.now().toIso8601String()}][$source][${exception.code}] '
          '${exception.message}\n${exception.stackTrace?.toString() ?? ''}\n';
      await file.writeAsString(line, mode: FileMode.append);
    } catch (_) {
      // 日志写入失败也不能让主流程崩溃
    }
  }
}

这里的技巧在于 _dumpToLocal 用了一个空 catch，日志写入是辅助功能，如果它自己抛异常，那就是坏了又坏，不值得让主流程跟着崩溃。日志文件会做大小限制，超过 500KB 就自动轮转，保留最近的日志。这个限制很重要，因为我把堆栈都写进去之后，日志膨胀速度是惊人的，不轮转的话存储空间很快会被占满。

跑通这一步之后，我写了一个测试页面，故意触发几类异常，确认都能在日志文件里看到对应的记录。然后再往下做业务层的嵌入。

3.2 第二步：把平台通道的服务端和客户端同时套上异常处理

平台通道是 Flutter 和 OpenHarmony 原生侧通信的桥梁，这里出问题最隐蔽。我的实操办法是写一个通道服务的规格文档，明确每一类方法调用可能出现的错误码，然后在 Dart 侧和 ArkTS 侧同时实现一遍错误处理。

以“注册后台任务”为例。这个调用的完整链路是：Dart 侧 channel.invokeMethod('registerWorkScheduler') -> ArkTS 侧 methodChannel.setMethodCallHandler 收到方法名 -> 调用 OpenHarmony 的 workScheduler API -> 返回结果。

ArkTS 侧的 catch 逻辑长这样：

typescript复制let methodCallHandler = (call: MethodCall) => {
  if (call.method === 'registerWorkScheduler') {
    try {
      let workInfo = new workScheduler.WorkInfo();
      // 设置工作参数
      workScheduler.startWork(workInfo);
      call.result(true);
    } catch (error) {
      const errCode = (error as BusinessError).code;
      let result = {
        code: mapErrorCode(errCode, 'workScheduler'),
        message: `registerWorkScheduler failed: ${errCode}`,
      };
      call.result(result); // 注意这里不抛异常，而是返回错误结果
    }
  }
};

这里有个容易踩的坑，很多新手在原生侧 catch 到错误之后直接调用 call.result(null) 或者干脆不调用 result，导致 Dart 侧永远等不到响应，最终超时。正确做法是无论成功失败，都必须通过 call.result 返回，并且把错误信息塞进返回值，而不是让平台通道在原生侧内部消化掉。

Dart 侧收到错误返回后，统一走到 AppExceptionWrapper.platformError。在这个环节我还会附加一个 context 字段，标记这个异常发生在哪个业务场景（比如是从首页顶部触发的还是后台任务触发的），方便后续排查。

3.3 第三步：业务关键代码里的异常捕获细化

管道通了，平台通道通了，第三步就是把业务代码里的捕获点逐个补上。这里我重点细化三个关键业务点的异常处理。

第一个，长时间未操作的检测。 这个要靠 Timer 定期检测前台是否有用户交互。检测过程本身异常概率低，但检测到之后的“是否弹窗”判断涉及上下文合法性检查。我加了代码来验证当前是否有可用的页面上下文，如果弹窗时页面已经在导航栈里被销毁，就放弃弹窗，但记录异常日志。

dart复制void _showRestReminderIfNeeded() {
  final navigator = GlobalKeyNavigator.currentContext;
  if (navigator == null) {
    ErrorReporter.report(
      AppExceptionWrapper(
        code: 'context-unavailable',
        message: '当前无可用上下文，无法弹窗',
        source: 'rest-reminder',
      ),
    );
    return;
  }
  // 正常弹窗逻辑
}

这个判断救了我好几次。App 被切后台之后，用户再切回来时导航栈可能已经重建，如果此时直接 Navigator.push，会抛出 “Looking up a deactivated widget's ancestor is unsafe” 异常。提前判断上下文避免了这个崩溃。

第二个，用眼时长统计的持久化。 统计数据的读写是本地文件操作，最容易出 EOF 异常、文件损坏异常。我给读写操作加了校验和机制：写入时记录数据包的 hash 值，读取时校验。如果校验失败，不崩溃，而是重置统计数据并写一条 ErrorLog。

第三个，通知栏点击事件的回调。 这个回调是从平台侧注入到 Dart 侧的，调用时机不可控。如果用户在 App 已经退出导航栈后点击通知，回调内部再执行跳转会出问题。我的处理方式是：回调入口统一用 WidgetsBinding.instance.addPostFrameCallback 包一层，把操作推迟到当前帧渲染完成后执行，如果还失败，走全局异常捕获通道。

这三块细化做完后，核心业务路径上基本没有裸奔的异常了。为了验证覆盖度，我把所有错误处理的接口列了个清单，对照着产品需求一条条确认：需求里每个“如果失败怎么办”的问题，都能在清单里找到对应的处理策略。

3.4 第四步：验证——用故障注入测试整个异常体系

这一块容易被忽略，却是整个项目里让我最踏实的部分。我专门做了一个“故障注入测试页”，开发模式下才能进入，用来手动触发各种异常场景，验证异常处理体系是否真的生效。

故障注入测试页里我加了这些拨动开关和按钮：

• 强制触发 dart 未捕获异常
• 强制触发 build 期异常
• 模拟平台通道返回 null
• 模拟平台通道返回错误码
• 模拟通知权限被拒绝
• 模拟文件写入失败

每个故障开关背后是真实代码路径，不是 mock。比如“模拟通知权限被拒绝”，是在 ArkTS 侧直接拒绝权限请求，真实走一遍用户拒绝权限后的链路。“模拟文件写入失败”是把日志目录权限改成只读，再触发一次写入。

这套故障注入测试跑下来的结果让我有点意外，大概有 20% 的注入场景在首次测试时表现不合格。最典型的例子是“平台通道返回 null”的用例：我原本以为代码里已经处理了 result ?? false，但实际操作时有一条调用路径没有处理空值，直接对 null 做了方法调用，抛出了 NoSuchMethodError。虽然被全局捕获了，但错误信息不直观。我在那个调用点补上了空值判断，错误提示变成了“平台返回空值，视为失败”，排查效率提升不少。

故障注入测试的结论是：异常处理体系必须在注入场景下验证过才算完成，光靠脑补覆盖不可能。 此后每次改动核心代码，我就回去跑一遍注入测试，确保没有把哪条异常处理逻辑改坏。

4. 常见问题与排查技巧实录

4.1 问题一：后台任务不触发，应用切后台后提醒全部失效

这是移植到 OpenHarmony 上遇到的第一个大坑，现象是：App 在前台时一切正常，一旦按 Home 键切到后台，计时停止、提醒不再弹出。排查时我首先看了 Dart 层的 Timer——果然还在走，因为 Timer 是应用进程内的逻辑，应用进程还在后台存活，Timer 理论上会继续执行。但实际没弹提醒，说明问题出在“提醒”的展示环节。

深入一层发现，OpenHarmony 的后台应用对弹窗类 UI 有限制，后台弹出全屏遮罩会被系统拦截。这个限制在 Android 上也有类似机制，但 OpenHarmony 的约束更严格，且不同版本行为不一致。

我的解决思路是拆分成前台和后台两条路径统一管理。前台时走全屏遮罩弹窗；后台时走系统通知；如果通知被系统拦截，就用本地闹钟再触发一次调度，确保用户回到前台后还能看到。这个方案的关键是引入了“后台任务的二次兜底”，不是只依赖一个定时器或者一个通知。

如果你也遇到类似问题，排查时先分清是计时没到，还是到点了没提醒。前者要查 Timer 是否被系统回收（在 OpenHarmony 上进程被冻结后 Timer 会停摆），后者要查通知是否被限制、弹窗是否被拦截。两者排查路径完全不同，不要混在一起。

4.2 问题二：MethodChannel 调用偶发超时，日志里没有异常堆栈

这是最像“幽灵问题”的一个。MethodChannel 调用有时成功有时超时，而且超时的时候 Dart 侧打出来的日志只是一个简单的 TimeoutException，完全没有堆栈指向原生侧。

后来我在原生侧也加了日志输出，对比时间戳才发现问题：首次调用时，ArkTS 侧要完成服务初始化，耗时超过了我在 Dart 侧设置的 3 秒超时；后续调用因为有缓存，就能通过。 Android 上没有这个初始化开销，所以我一开始没往这个方向想。

解决办法是首次启动时做一个预热调用，把一个轻量方法发到原生侧，强制触发初始化，之后再正常走业务调用。预热过程中如果失败，直接走降级模式，不等初始化完成。如果你遇到了类似的偶发超时，先别急着改代码，先在原生侧打日志确认每次调用的实际耗时，看是否和首次初始化有关。

4.3 问题四：通知权限被拒后，整个提醒链路不工作

权限被用户拒绝是这类应用的高频场景。我的第一个版本里，权限被拒只会让系统通知失效，但全屏弹窗路径还在。问题出在更隐蔽的地方：用户在权限弹窗里点了“拒绝且不再询问”之后，系统会直接返回一个固定的错误，我的代码每次都尝试请求权限，每次都被秒拒，浪费资源还容易让用户烦躁。

后来我调整了策略：第一次拒绝后，不再自动重复请求，而是显示一个引导页，告诉用户“开启通知权限后可以获得更好的休息提醒”，把选择权交还给用户。同时，不管权限状态如何，全屏弹窗和声音提醒始终作为保底方案。

这个案例给我的教训是：错误处理不仅是技术问题，也是产品体验问题。 有些异常场景不能一味重试，而是要区分“临时性失败”和“永久性失败”。临时性失败（比如服务暂不可用）要重试，永久性失败（比如用户主动拒绝权限）要求变。

4.4 排查工具与日志查看技巧速查

给出一张我常用的排查对照表，方便你对照自己的场景快速定位问题。

日志查看方面，我习惯在开发调试时打开两个终端窗口，一个专门看 Flutter 的 logcat 输出，一个过滤 OpenHarmony 原生侧的 hilog 日志，两边时间戳对齐后就能还原一次调用的完整链路。关键是把两边的日志打到同一个时间精度，否则很难对上号。

5. 稳定性兜底与后续扩展建议

5.1 自恢复机制的实战设计

错误处理做到前面那一步，已经能把问题“接住”了，但距离好产品还有距离。真正让 App 在用户手里“感觉不到问题”的，是自恢复机制。

我在 App 里加了一个等级化自恢复策略。第一级是“局部重试”：比如通知发送失败，我先判断错误码是不是临时性的（比如 system_busy），如果是，延迟五秒后重试一次，最多重试两次。第二级是“降级切换”：局部重试仍然失败，就切到备用方案（全屏弹窗）。第三级是“状态复位”：如果连续三次关键操作都失败，说明 App 内部状态可能已经乱了，就触发一次状态机整体复位，清空所有非持久化状态，重新初始化。

自恢复的逻辑必须和目标业务强绑定。对视力提醒来说，用户要的是“到点被打断”，所以自恢复的优先级从高到低是：弹窗 > 通知 > 声音 > 下次打开提示。如果弹窗和通知都失败，声音提醒还是可以强制播报出来的，前提是音频权限是允许的。

5.2 面向后续版本的异常监控扩展

这个项目现在跑在开发板上，数据量小，本地日志够用。但如果后续版本要推到更广泛的用户手里，异常监控必须升级。

我的建议是把错误上报的管道做一次抽象，预留三个远端上报的接口：实时上报、批量上报、堆栈拉取。实时上报用于严重错误（比如自恢复失败的场景），批量上报用于普通错误（攒满 20 条或 30 秒上报一次），堆栈拉取用于用户反馈问题时后台主动拉取日志。

上报的数据结构建议至少要包含：错误码、错误来源、设备信息（系统版本、型号、语言）、用户行为上下文（当前页面、最近操作）、时间戳。这些字段缺一不可，没有设备信息和行为上下文，错误码再清晰也很难远程定位问题。

5.3 测试驱动与故障注入如何融入日常开发

这套错误处理体系最大的受益点，是让开发过程本身变得更安全。我现在每加一个新功能，要求自己必须同时完成两件事：一个是功能正常的 happy path 测试，另一个是故障注入测试。故障注入不是可选项，是必选项。

日常开发中我形成了一个固定的检查清单：

• 这个功能调用了哪些平台能力？这些能力各自失败时会抛什么错误？
• 这些错误里，哪些是临时性失败需要重试，哪些是永久性失败需要引导用户？
• 如果这个功能整体失效，用户感知是什么？有没有备用方案？
• 新功能的异常日志是否带足了上下文信息，能不能脱离现场调试独立排查？

把这些问题过一遍，代码的质量会明显提升。不要觉得这是浪费时间，实际上它给你的不是额外的工作量，而是降低后期 debug 的时间成本。我在这套体系上投入的时间，在第一次真机联调时全部值回来了——那些最早暴露的异常，几乎都能靠日志最直接地定位，没有哪一个需要靠猜。

最后给一点我的个人感受：错误处理这套东西，单看每一个 try/catch、每一个异常类、每一条日志，都平淡无奇，但它们组合在一起，就是 App 稳定性的根基。在 OpenHarmony 这样一个 Flutter 生态还在快速生长的平台上做事，这个根基尤其重要。把这段路走通之后，我再去看那些自称“稳定”的跨平台应用，第一反应已经变成了：你有几层异常兜底？你失败后的降级路径是什么？敢不敢做故障注入测试？这些问题比功能清单更能衡量一个应用的真实成熟度。