# EasyNode HarmonyOS (OHOS) 构建说明

## 前置环境

| 工具 | 版本要求 | 说明 |
|------|----------|------|
| DevEco Studio | 5.0+ | HarmonyOS IDE、SDK 管理、签名配置 |
| HarmonyOS SDK | 5.0.0(12)+ | 编译目标 |
| Flutter-OH SDK | 3.41.10-ohos | 社区 fork（CPF-Flutter），命令行工具为 `flutter-oh` |
| Node.js | ≥ 18.15 | hvigor 构建系统依赖 |
| JDK | 17 | 构建工具链依赖 |

## dependency_overrides 说明

Flutter 标准插件不识别 OHOS 平台，需要通过 `dependency_overrides` 指向 CPF-Flutter 社区适配版本：

| 插件 | 来源 | 分支/版本 | 说明 |
|------|------|-----------|------|
| `shared_preferences` | `CPF-Flutter/flutter_packages` | 默认分支 | 键值存储 |
| `path_provider` | `CPF-Flutter/flutter_packages` | 默认分支 | 文件路径 |
| `url_launcher` | `CPF-Flutter/flutter_packages` | 默认分支 | 打开外部链接 |
| `flutter_secure_storage` | `CPF-Flutter/fluttertpc_flutter_secure_storage` | `br_v9.2.4_ohos` | 加密存储 |
| `flutter_secure_storage_ohos` | 同上 | `br_v9.2.4_ohos` | OHOS 平台实现 |
| `package_info_plus` | `CPF-Flutter/flutter_plus_plugins` | `br_package_info_plus-v8.1.0_ohos` | 包信息 |
| `share_plus` | `CPF-Flutter/flutter_plus_plugins` | `br_share_plus-v12.0.1_ohos` | 文件分享 |

额外依赖（非 override，直接添加到 dependencies）：

| 插件 | 来源 | 分支/版本 | 说明 |
|------|------|-----------|------|
| `file_picker_ohos` | `packages/file_picker_ohos` | vendored `br_v10.3.8_ohos` native OHOS files | 文件选择器，仅注册 OHOS 原生实现 |

## ohos_patch.sh 运行时补丁

部分 pub cache 中的包不识别 OHOS 平台，需要在 `pub get` 后运行 `ohos_patch.sh` 进行修补。**每次执行 `pub get` 后都需要重新运行。**

补丁内容：

| 目标包 | 修补内容 |
|--------|----------|
| `code_assets` os.dart | 添加 `OS.ohos` 枚举值到 OS 类和 values 列表 |
| `code_assets` syntax.g.dart | 添加 `OSSyntax.ohos` 枚举值到 OSSyntax 类和 values 列表 |
| `flutter_secure_storage` | 将 `throw UnsupportedError` 替换为 `return <String, String>{}` 兜底 |
| `xterm` shortcuts.dart | 在 switch 语句中添加 `default:` 分支避免 OHOS 平台抛异常 |

补丁覆盖两个 pub cache 目录：
- `~/.pub-cache/hosted/pub.dev/`
- `~/PUB/hosted/pub.flutter-io.cn/`（PUB_CACHE 环境变量指定）
- `~/PUB/git/`（git 依赖缓存）

`file_picker_ohos` 已改为仓库内本地包，只声明 OHOS 平台，避免 Android
release 构建时和官方 `file_picker` 同时产出 `com.mr.flutter.plugin.filepicker.*`
类导致 R8 duplicate class。

## 构建步骤

### Debug 构建 & 运行

```bash
cd native

# 1. 获取依赖
flutter-oh pub get

# 2. 运行补丁（每次 pub get 后必须执行）
bash ohos_patch.sh

# 3. 连接设备后运行
flutter-oh run
```

### Release 构建（HAP）

```bash
cd native

flutter-oh pub get
bash ohos_patch.sh
flutter-oh build hap --release
```

构建产物位于 `ohos/entry/build/default/outputs/` 目录，后缀为 `.hap`。

### Release 构建（APP，用于上架应用市场）

上架华为应用市场（AppGallery）需要提交 `.app` 格式的包，而非 `.hap`。

**HAP vs APP 区别：**
- **HAP** (HarmonyOS Ability Package)：模块级包，每个 module 编译产出一个 `.hap`，可用于本地安装测试
- **APP** (Application Package)：应用级包，将一个或多个 HAP 打包在一起，**上架应用市场必须提交此格式**

构建方式：

```bash
flutter-oh build app --release
```

### 清理构建缓存

遇到编译异常时可尝试清理缓存后重新构建：

```bash
rm -rf .dart_tool/hooks_runner/
rm -rf build/
rm -rf ohos/entry/build/
flutter-oh pub get
bash ohos_patch.sh
flutter-oh run
```

## 签名配置

Debug 签名由 DevEco Studio 自动生成，配置在 `ohos/build-profile.json5` 中。

Release 签名需要华为开发者证书，请在 DevEco Studio 中配置：
- Project Structure → Signing Configs → 添加 Release 签名
- 或手动编辑 `ohos/build-profile.json5` 的 `signingConfigs`

## 注意事项

- Flutter-OH SDK 是社区维护的 fork（CPF-Flutter），非 Google 官方支持
- `build-profile.json5` 中的 debug 签名路径为本地路径，不应提交到仓库
- 当前 CI/CD 暂无 OHOS 构建流水线，需本地构建