AtomGit Flutter 鸿蒙客户端：Flutter 鸿蒙应用的错误处理与优雅降级策略

鸿蒙平台的不确定性比 Android/iOS 更大------你的错误处理需要更保守、更全面。

一、三层错误防护体系

复制代码

┌─────────────────────────────┐
│  第1层：全局 Flutter 异常捕获  │  FlutterError.onError
├─────────────────────────────┤
│  第2层：初始化步骤追踪         │  errorStep + 外层 try-catch
├─────────────────────────────┤
│  第3层：操作级 try-catch       │  每个用户操作独立捕获
└─────────────────────────────┘

二、第1层：全局错误拦截

dart 复制代码

FlutterError.onError = (details) {
  FlutterError.presentError(details);  // 保留默认红色界面
  debugPrint('[E-Brufen] FLUTTER ERROR: ${details.exceptionAsString()}');
};

FlutterError.onError 捕获 Flutter 框架层错误（布局溢出、类型错误等）。保留 presentError 确保开发时能看到红色错误页，同时添加 debugPrint 用于日志追溯。

三、第2层：初始化容错

dart 复制代码

String? errorStep;

try {
  errorStep = 'Hive init';
  try {
    await Hive.initFlutter();
  } catch (e) {
    Hive.init(Directory.systemTemp.path);  // 降级
  }

  errorStep = 'Settings init';
  final settings = AppSettings();
  await settings.init();

  errorStep = 'MoodStorage init';
  final moodStorage = MoodStorage();
  await moodStorage.init();

  errorStep = null;  // 成功
  runApp(EBrufenApp(settings: settings, moodStorage: moodStorage));

} catch (e, _) {
  debugPrint('[E-Brufen] INIT FAILED at $errorStep: $e');
  runApp(_ErrorApp(errorStep ?? '?', e.toString()));
}

关键设计：

errorStep 变量精确定位失败位置
内层 try-catch 处理已知可恢复错误（Hive 路径问题）
外层 try-catch 兜底未知错误
最坏情况下启动 _ErrorApp------至少不是白屏

四、错误兜底 UI

dart 复制代码

class _ErrorApp extends StatelessWidget {
  final String step;
  final String message;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        backgroundColor: Colors.white,
        body: Center(
          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: TextStyle(fontSize: 14, color: Colors.orange)),
              Container(
                padding: EdgeInsets.all(12),
                decoration: BoxDecoration(
                  color: Colors.grey.shade100,
                  borderRadius: BorderRadius.circular(8),
                ),
                child: Text(message,
                  style: TextStyle(fontSize: 12, color: Colors.red)),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

信息分层给不同受众：

受众	看到	信息
用户	❌ + "初始化失败"	知道出了问题
技术支持	"Step: Hive init"	知道在哪一步失败
开发者	完整错误 message	可以定位根因

五、第3层：操作级错误处理

dart 复制代码

Future<void> _quickCheckIn(BuildContext context, MoodType mood) async {
  final messenger = ScaffoldMessenger.of(context);
  try {
    await moodStorage.insert(MoodEntry(...));
    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),
        backgroundColor: Colors.red.shade400,
      ),
    );
  }
}

用户操作的处理原则：

成功：极短反馈（1 秒），不打断用户
失败：稍长反馈（2 秒），红色醒目，显示错误信息
绝不崩溃（try-catch 包裹）

★ Insight ─────────────────────────────────────

鸿蒙 Flutter 的操作错误率比 Android/iOS 更高------不是因为代码问题，而是因为平台兼容性。文件系统差异、Hive CE 的边界情况、引擎版本不匹配都可能导致操作失败。在鸿蒙上，每一次用户操作都值得被 try-catch 包裹 。

─────────────────────────────────────────────────

六、鸿蒙特有的错误类型

错误	原因	处理
Hive 初始化失败	文件系统路径不兼容	降级到 temp dir
构建时签名错误	Profile 过期或包名不匹配	检查 build-profile.json5
运行时崩溃	引擎版本不兼容	更新 Flutter/鸿蒙 SDK

七、生产环境的日志策略

当前 E-Brufen 使用 debugPrint，生产环境应升级：

dart 复制代码

// 未来改进：写入本地日志文件
void log(String msg) {
  final file = File('${_logDir.path}/ebrufen.log');
  file.writeAsStringSync(
    '[${DateTime.now()}] $msg\n',
    mode: FileMode.append,
  );
}

小结

三层错误处理体系是鸿蒙 Flutter 应用的"安全气囊"------你希望永远不需要它，但一旦需要，它能救你的命。核心原则：永远不让用户看到白屏，永远给出有用的错误信息。

作者简介 ：E-Brufen Dev，Flutter & 鸿蒙开发者，专注于跨平台移动应用开发与心理健康数字化,项目地址：AtomGit - E-Brufen。