鸿蒙（HarmonyOS）上的 Flutter 运行环境与 Android/iOS 有所不同——某些 Flutter 平台插件可能不可用，文件系统路径也不同。E-Brufen 作为一个纯离线应用，必须在初始化阶段处理好各种异常场景，确保应用"至少能启动"。本文将完整展示 E-Brufen 的错误处理架构：从全局异常捕获到逐级降级，再到 UI 层的用户友好提示。

1. 错误处理的总体架构

E-Brufen 的错误处理分为四层：

第一层：FlutterError.onError（全局捕获）
    ↓
第二层：分步初始化 + errorStep 追踪（精确诊断）
    ↓
第三层：Hive 平台降级（文件系统容错）
    ↓
第四层：_ErrorApp 兜底 UI（用户友好）

每一层都是上一层失败后的"安全网"。这个设计确保了无论哪一步出问题，用户看到的都不是白屏。

2. 第一层：全局 Flutter 异常捕获

FlutterError.onError = (details) {
  FlutterError.presentError(details);
  debugPrint('[E-Brufen] FLUTTER ERROR: ${details.exceptionAsString()}');
};

这个回调捕获所有 Flutter 框架层的未处理异常。FlutterError.presentError(details) 保持默认行为（在控制台打印红色错误），debugPrint 添加统一的前缀 [E-Brufen] 方便日志过滤。

在鸿蒙调试时，可以通过 hdc shell hilog 查看这些日志输出——Hilog 是鸿蒙的系统日志工具，相当于 Android 的 logcat。

3. 第二层：分步初始化 + 精确追踪

鸿蒙环境下，最常见的启动失败发生在初始化阶段。E-Brufen 将整个初始化过程拆分为三步，每步都独立 try/catch，并用 errorStep 变量追踪失败位置：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // ... 状态栏设置 ...

  FlutterError.onError = (details) { ... };

  String? errorStep;

  try {
    // ── 第1步：Hive ──
    errorStep = 'Hive init';
    debugPrint('[E-Brufen] Step 1: Hive...');
    try {
      await Hive.initFlutter();
    } catch (e) {
      debugPrint('[E-Brufen] initFlutter failed, using temp dir: $e');
      Hive.init(Directory.systemTemp.path);
    }

    // ── 第2步：Settings ──
    errorStep = 'Settings init';
    debugPrint('[E-Brufen] Step 2: Settings...');
    final settings = AppSettings();
    await settings.init();

    // ── 第3步：MoodStorage ──
    errorStep = 'MoodStorage init';
    debugPrint('[E-Brufen] Step 3: MoodStorage...');
    final moodStorage = MoodStorage();
    await moodStorage.init();

    // ── Launch ──
    errorStep = null;
    debugPrint('[E-Brufen] Launching app!');
    runApp(EBrufenApp(settings: settings, moodStorage: moodStorage));
  } catch (e, _) {
    debugPrint('[E-Brufen] INIT FAILED at $errorStep: $e');
    runApp(_ErrorApp(errorStep ?? '?', e.toString()));
  }
}

关键设计点：

外层 try/catch：覆盖整个 main 函数。如果某一步 errorStep 被设置但未成功进入下一步，外层的 catch 会打印 INIT FAILED at Hive init: ... 这样的精确消息。

每步独立的 debugPrint：在鸿蒙设备上，如果应用白屏且无法连接调试器，这些日志就是唯一的诊断线索。

errorStep = null：只有所有步骤成功后，才将 errorStep 置空。这有一个微妙的设计——如果代码执行到 runApp() 的时候抛出异常（比如 Widget 构建错误），外层的 catch 看到 errorStep 是 null，会打印 INIT FAILED at ?，说明失败发生在启动阶段而非初始化阶段。

4. 第三层：Hive 平台降级

第一层的细分中，最可能出问题的是 Hive 初始化。Hive CE 提供了两种初始化方式：

try {
  await Hive.initFlutter();       // 使用 Flutter 平台路径（首选）
} catch (e) {
  debugPrint('[E-Brufen] initFlutter failed, using temp dir: $e');
  Hive.init(Directory.systemTemp.path);  // 回退到系统临时目录
}

Hive.initFlutter() 内部调用 getApplicationDocumentsDirectory()——这个 API 在鸿蒙平台上由 path_provider 插件提供支持。如果插件不兼容或权限不足，就会抛异常。

回退方案 Hive.init(Directory.systemTemp.path) 使用 Dart 的原生 dart:io API，不依赖 Flutter 平台插件。代价是数据存在系统临时目录中，可能在系统清理时被删除。但相比"应用完全打不开"，这是可接受的权衡。

鸿蒙特殊场景：部分鸿蒙设备对应用沙盒目录的访问限制比 Android 严格。E-Brufen 上线前的提交记录显示，开发团队经历了从 path_provider 到 systemTemp 回退的调试过程，最终确定了两层 fallback 策略。

5. 第四层：_ErrorApp 兜底 UI

当所有降级策略都失败时，至少给用户一个明确的错误提示——而不是白屏：

class _ErrorApp extends StatelessWidget {
  final String step;
  final String message;
  const _ErrorApp(this.step, this.message);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        backgroundColor: Colors.white,
        body: Center(
          child: Padding(
            padding: const EdgeInsets.all(32),
            child: Column(
              mainAxisSize: MainAxisSize.min,
              children: [
                const Icon(Icons.error_outline, size: 64, color: Colors.red),
                const SizedBox(height: 16),
                const Text('初始化失败',
                    style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold)),
                const SizedBox(height: 8),
                Text('Step: $step',
                    style: const TextStyle(fontSize: 14, color: Colors.orange)),
                const SizedBox(height: 12),
                Container(
                  padding: const EdgeInsets.all(12),
                  decoration: BoxDecoration(
                    color: Colors.grey.shade100,
                    borderRadius: BorderRadius.circular(8),
                  ),
                  child: Text(message,
                      style: const TextStyle(fontSize: 12, color: Colors.red),
                      textAlign: TextAlign.left),
                ),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

这个错误界面提供了：

1. 红色错误图标——视觉上的"出错了"信号
2. “初始化失败”——中文错误标题，用户能理解
3. Step 信息——用橙色显示失败步骤，方便技术支持
4. 灰色背景的错误详情——20 号字体，可滚动阅读

注意 debugShowCheckedModeBanner: false——即使在错误界面，也要保持干净。

6. 运行时异常：快速打卡的 try/catch

除了初始化阶段，运行时也需要错误处理。以首页的快速心情打卡为例：

Future<void> _quickCheckIn(BuildContext context, MoodType mood) async {
  final messenger = ScaffoldMessenger.of(context);
  try {
    final now = DateTime.now();
    moodStorage.insert(MoodEntry(
      moodType: mood,
      createdAt: now,
      updatedAt: now,
    ));
    messenger.showSnackBar(
      const SnackBar(content: Text('已记录 ✅'),
        duration: Duration(seconds: 1),
        behavior: SnackBarBehavior.floating,
      ),
    );
  } catch (e) {
    messenger.showSnackBar(
      SnackBar(content: Text('保存失败: $e'),
        duration: const Duration(seconds: 2),
        behavior: SnackBarBehavior.floating,
        backgroundColor: Colors.red.shade400,
      ),
    );
  }
}

成功时显示绿色 SnackBar（1 秒自动消失），失败时显示红色 SnackBar（2 秒，包含错误信息）。behavior: SnackBarBehavior.floating 让 SnackBar 悬浮在底部上方，不会遮挡系统导航栏。

7. 完整的错误处理链路总结

场景	处理方式	用户看到
Flutter 框架异常	FlutterError.onError 日志 + 默认红色界面	红色异常界面
Hive.initFlutter() 失败	回退到 Hive.init(systemTemp)	正常（数据在临时目录）
Settings/MoodStorage 初始化失败	外层 catch 捕获	_ErrorApp 灰色错误页
心情打卡写入失败	方法内 try/catch	红色 SnackBar"保存失败"
所有未知异常	外层兜底	_ErrorApp 含完整错误信息

8. 鸿蒙特有的错误场景

在实际开发中，E-Brufen 团队遇到并处理的鸿蒙特有场景：

1. path_provider 不可用：某些鸿蒙版本或设备上，getApplicationDocumentsDirectory() 返回 null。解决方案：Hive 回退到 systemTemp。
2. 音频播放器不可用：鸿蒙 Flutter 引擎的音频插件支持有限。E-Brufen 最终去掉了所有原生音频代码，转而使用视觉动画和触觉反馈。
3. 权限模型差异：鸿蒙没有 Android 的 INTERNET 权限概念，因此 E-Brufen 从 module.json5 中移除了网络权限声明。

总结

"优雅降级"不只是一种技术手段，更是一种产品哲学——不追求零错误，而是确保任何错误都不会让用户卡在空白屏幕上。E-Brufen 的四层错误处理架构，从全局异常捕获、分步诊断、平台降级到兜底 UI，形成了一个完整的稳定性保障体系。

---

上一篇：数据层测试：MoodStorage 的 CRUD 集成验证

下一篇：AppGallery 应用发布全流程：从签名到上架

---

E-Brufen Dev, Flutter & 鸿蒙开发者，项目地址：AtomGit - E‑Brufen 。