欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

Flutter 的口号是 “Write Once, Run Everywhere”。但 “Run Everywhere” 并不意味着 “Run Exactly the Same Everywhere”。
在实际开发中，我们经常需要针对不同平台编写特定的代码：

• Android: 使用 Material Design 风格，调用 JNI。
• iOS: 使用 Cupertino 风格，调用 Objective-C。
• Web: 处理浏览器差异，调用 JS。
• OpenHarmony: 处理鸿蒙特有的 ArkTS 交互，适配分布式能力。

dart:io 提供了基础的 Platform 类，但它不仅无法识别 Web（因为 dart:io 在 Web 不可用），更无法区分 原生 Android 和 OpenHarmony (兼容 Android 模式)，甚至无法识别 纯血鸿蒙 (HarmonyOS NEXT)。

platform 包（及其改进版 platform_device_id 或社区封装）旨在提供一个统一的、可测试的、能准确识别所有平台的解决方案。
对于鸿蒙开发者，最痛的痛点莫过于：Platform.isAndroid 在鸿蒙手机上返回 true，导致应用误以为自己跑在安卓上，调用了 GMS 服务从而崩溃。

一、核心原理与识别机制

1.1 dart:io Platform 的局限性

Platform.isAndroid 的判断逻辑是基于 Dart VM 编译时的目标架构或运行时的系统属性（uname）。
在 OpenHarmony 的兼容模式下，底层 Linux 内核依然保留了大量 Android 特征，因此 Dart VM 很难区分。

1.2 platform 包的设计

package:platform 提供了一个抽象层 Platform 接口和两个实现：

• LocalPlatform: 封装了 dart:io 的静态属性。
• FakePlatform: 用于单元测试，允许你模拟“我在 Android 上”或“我在 Windows 上”。

虽然 package:platform 本身没有魔法来识别鸿蒙，但它提供了一个 可测试的接口。我们可以在此基础上扩展自己的鸿蒙识别逻辑。

二、核心 API 详解与进阶封装

2.1 基础用法

import 'package:platform/platform.dart';

void main() {
  // 使用 LocalPlatform (真实环境)
  const platform = LocalPlatform();

  if (platform.isAndroid) {
    print('Running on Android');
  } else if (platform.isMacOS) {
    print('Running on macOS');
  }

  // 获取环境变量
  print('PATH: ${platform.environment['PATH']}');
}

2.2 单元测试 Mock

这是 package:platform 最大的价值。

import 'package:flutter_test/flutter_test.dart';
import 'package:platform/platform.dart';

void main() {
  test('Show Android UI', () {
    // 模拟 Android 环境
    final fakePlatform = FakePlatform(operatingSystem: 'android');
    
    final widget = MyWidget(platform: fakePlatform); // 注入
    // expect(...)
  });
}

三、OpenHarmony 平台适配实战：精准识别鸿蒙

在鸿蒙开发中，我们通常面临三种情况：

1. 纯血鸿蒙 (HarmonyOS NEXT): 系统内核完全改变，不再兼容 Android APK。此时 Platform.isOhos (如果有的话) 应该为 true。
2. 兼容模式 (OpenHarmony): 基于 Linux 内核，兼容 AOSP。此时 Platform.isAndroid 为 true。
3. 原生 Android: 普通安卓手机。

为了准确区分，我们需要结合 系统属性 (Build.prop) 或 特定文件。

3.1 实战：封装 OhosPlatform 工具类

import 'dart:io';
import 'package:platform/platform.dart';
import 'package:process_run/shell.dart'; // 需要 process_run 执行命令

class OhosPlatform extends LocalPlatform {
  const OhosPlatform();

  /// 是否运行在鸿蒙设备上 (包括兼容模式和纯血鸿蒙)
  Future<bool> get isHarmonyOS async {
    if (isAndroid) {
      // 检查系统属性
      // 鸿蒙系统通常会有 hw_sc.build.os.releasetype 或 ro.build.version.release 包含 Harmony
      try {
        final result = await Process.run('getprop', ['ro.build.version.release']);
        final version = result.stdout.toString();
        // 注意：不同厂商/版本可能不同，需真机验证
        // 比如华为手机可能是 HarmonyOS 4.0
        return version.contains('Harmony') || await _checkHwProps();
      } catch (e) {
        return false;
      }
    }
    return false; // 这里暂不考虑纯血鸿蒙的 Dart SDK 实现细节
  }

  // 检查华为特有属性
  Future<bool> _checkHwProps() async {
    try {
      final res = await Process.run('getprop', ['ro.build.hw_emui_api_level']);
      return res.stdout.toString().isNotEmpty;
    } catch (_) {
      return false;
    }
  }

  /// 是否是纯血鸿蒙 (假设 Dart SDK 已支持)
  // bool get isOhos => operatingSystem == 'ohos'; 
}

3.2 运行时差异化逻辑

void initServices() async {
  final platform = const OhosPlatform();

  if (await platform.isHarmonyOS) {
    print('Loading HMS Core...');
    // 初始化华为推送、华为地图
  } else if (platform.isAndroid) {
    print('Loading GMS Core...');
    // 初始化 Firebase、Google Maps
  } else if (platform.isIOS) {
    print('Loading iOS Services...');
  }
}

四、安全与最佳实践

4.1 不要过度依赖 Platform.isAndroid

在 Flutter for OpenHarmony 的 roadmap 中，官方正在推进将 ohos 作为一个独立的一级平台（First-class Platform）加入到 Dart SDK 中。
这意味着未来：

• Platform.isAndroid -> false
• Platform.operatingSystem -> 'ohos'

建议：在代码中尽早封装一层 AppPlatform 接口，将所有 Platform.isXXX 的调用收拢到一个文件。这样未来 Dart SDK 更新时，你只需要改这一个文件，而不用全项目搜索替换。

// lib/core/platform_utils.dart
class AppPlatform {
  static bool get isMobile => Platform.isAndroid || Platform.isIOS || isOhos;
  
  // 预留给未来的实现
  static bool get isOhos => Platform.operatingSystem == 'ohos';
}

4.2 Web 平台的坑

千万记得，dart:io 在 Web 上是不能用的。如果你的代码需要支持 Web，必须使用 kIsWeb 常量进行判断，或者使用 universal_io 库。

package:platform 虽然提供了接口，但在 Web 上使用 LocalPlatform 会直接抛出异常（因为它依赖 dart:io）。正确做法是使用 FakePlatform 或者条件导入。

五、总结

platform 包虽然看起来只是 dart:io 的一层薄薄的封装，但它体现了 可测试性 (Testability) 的架构思想。

对于 OpenHarmony 开发者，理解平台的本质差异（是兼容 Android 还是纯血鸿蒙）至关重要。通过组合 getprop 命令和系统属性检查，我们可以在当前过渡阶段实现精准的平台识别，确保应用在华为手机、荣耀手机以及其他鸿蒙设备上都能正确加载对应的原生服务。

回顾核心价值：

1. LocalPlatform: 生产环境使用。
2. FakePlatform: 测试环境使用。
3. OhosPlatform: 自定义扩展，解决鸿蒙识别难题。

---