harmony-flutter - 无书的书

最后修改人	无书大王
最后修改时间	2026-03-23 05:27:41
创建人	无书大王
创建时间	2026-03-23 05:27:41

该文档由无书大王创建于 2026-03-23 05:27:41 ，无书大王在 2026-03-23 05:27:41 修改了该文档。

[TOCM]

# Flutter 鸿蒙端配置指南

本文档记录了为Flutter项目添加鸿蒙(OpenHarmony)平台支持的完整配置步骤。

## 环境要求

| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| Flutter SDK | 3.27.4-ohos | 鸿蒙适配版本 |
| Java | JDK 17 | 必须使用JDK 17 |
| Node.js | 18+ | 构建工具依赖 |
| ohpm | 1.6+ | 鸿蒙包管理器 |
| HarmonyOS SDK | API 18+ | DevEco Studio 5.1+ |
| Python | 3.8-3.11 | 可选 |
| Git | 最新版 | 必须配置到PATH |

## 配置步骤

### 1. 配置Windows环境变量

在Windows系统中配置以下环境变量（通过"编辑系统环境变量"设置）：

```powershell
# 鸿蒙SDK相关
TOOL_HOME=H:\Program Files\Huawei\DevEco Studio
DEVECO_SDK_HOME=%TOOL_HOME%\sdk

# 添加到PATH（放在最前面）
%TOOL_HOME%\tools\ohpm\bin
%TOOL_HOME%\tools\hvigor\bin
%TOOL_HOME%\tools\node\bin
```

### 2. 配置Flutter SDK环境变量

```powershell
# Flutter鸿蒙版SDK（放在PATH最前面）
PATH=H:\SDK\opflutter\flutter_flutter-br_3.27.4-ohos-1.0.4\bin;%PATH%

# 国内镜像（加速下载）
PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# PUB缓存目录（可选，自定义路径）
PUB_CACHE=G:\pub\cache
```

### 3. 配置npm和ohpm镜像

在用户目录 `C:\Users\<用户名>\` 下创建以下文件：

**`.npmrc` 文件内容：**
```
registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/
strict-ssl=false
```

**`.ohpmrc` 文件内容：**
```
registry=https://repo.harmonyos.com/ohpm/
strict_ssl=false
```

### 4. 初始化鸿蒙Flutter SDK

如果鸿蒙Flutter SDK是从压缩包解压的（非git clone下载），需要初始化git：

```powershell
cd H:\SDK\opflutter\flutter_flutter-br_3.27.4-ohos-1.0.4
git init
git remote add origin https://gitcode.com/openharmony-sig/flutter_flutter.git
git add -A
git commit -m "init"
```

### 5. 为项目添加ohos平台

```powershell
cd <项目目录>
flutter create --platforms ohos .
flutter pub get
```

### 6. 配置签名

用DevEco Studio打开项目的ohos工程：
```
File → Project Structure → Signing Configs
勾选 "Automatically generate signature"
```

### 7. 验证环境

```powershell
flutter doctor -v
```

确保 **Flutter** 和 **OpenHarmony** 都显示正常。

## 常用命令

```powershell
# 查看已连接设备
flutter devices

# 编译debug版本
flutter build hap --debug

# 编译release版本
flutter build hap --release

# 编译profile版本
flutter build hap --profile

# 运行到鸿蒙设备
flutter run -d <device-id>

# 安装hap包
hdc -t <deviceId> install <hap文件路径>

# 清除项目缓存
flutter clean
```

## 项目文件修改说明

### pubspec.yaml 修改

由于鸿蒙版Flutter基于3.27.4，Dart版本为3.6.2，需要调整：

```yaml
environment:
  sdk: ^3.6.0

dev_dependencies:
  flutter_lints: ^4.0.0
  # 注意：flutter_test可能与鸿蒙版存在版本冲突，如遇问题可暂时移除
```

### ohos目录结构

```
ohos/
├── AppScope/              # 应用全局配置
│   ├── app.json5          # 应用配置
│   └── resources/         # 全局资源
├── entry/                 # 主模块
│   ├── src/main/          # 主代码
│   │   ├── ets/           # ArkTS代码
│   │   ├── resources/     # 资源文件
│   │   └── module.json5   # 模块配置
│   └── build-profile.json5
├── hvigor/                # 构建工具配置
├── build-profile.json5    # 构建配置
└── oh-package.json5       # 依赖配置
```

## 重要注意事项

### 环境相关

1. **Git必须配置到PATH**：Windows环境下，如果没有将Git的cmd目录添加到PATH，flutter命令会闪退

2. **Flutter SDK版本**：鸿蒙版Flutter是基于官方3.27.4版本构建的兼容包，同时支持Android、iOS和OpenHarmony，会替代官方SDK

3. **版本差异**：
   - 鸿蒙版Flutter：3.27.4-ohos-1.0.4
   - 官方版Flutter：3.29.3+
   - 部分官方新特性可能不可用

4. **切换SDK后**：
   - 删除 `<flutter_sdk>/bin/cache` 目录
   - 在项目中执行 `flutter clean`

5. **环境变量优先级**：确保鸿蒙版Flutter SDK路径在PATH的最前面，否则可能使用旧版本

### 构建相关

1. **模拟器限制**：
   - 模拟器只支持 Mac(arm64)
   - Windows和Mac(x86)模拟器暂不支持
   - 模拟器不支持vulkan，需要关闭impeller

2. **关闭impeller**（如模拟器需要）：在 `ohos/entry/src/main/resources/rawfile/buildinfo.json5` 中设置：
   ```json
   {
     "string": [
       {
         "name": "enable_impeller",
         "value": "false"
       }
     ]
   }
   ```

3. **版本匹配**：debug/release/profile 模式必须匹配使用，否则会出现白屏或崩溃

4. **项目与插件同磁盘**：Flutter项目和依赖的插件项目必须在同一磁盘

### 运行相关

1. **签名问题**：如果安装报错 `fail to verify pkcs7 file`，执行：
   ```powershell
   hdc shell param set persist.bms.ohCert.verify true
   ```

2. **权限配置**：应用权限需要在 `ohos/entry/src/main/module.json5` 的 `requestPermissions` 中声明

3. **常用权限**：
   - 剪贴板：`ohos.permission.READ_PASTEBOARD`
   - 保存图片：`ohos.permission.WRITE_IMAGEVIDEO`

### 常见错误

| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| `The Flutter directory is not a clone of the GitHub project` | 缺少.git目录 | 执行git init初始化 |
| `Wrong full snapshot version` | 引擎版本不匹配 | 确保debug/release模式匹配 |
| `The SDK license agreement is not accepted` | SDK版本不匹配 | 升级ohos项目结构到API 12 |
| `Cannot find belonging project path` | hvigor路径问题 | 修改hvigor配置文件 |
| `fail to verify pkcs7 file` | 签名验证失败 | 设置bms.ohCert.verify为true |

## 相关文档

- [OHOS.md](./OHOS.md) - 官方鸿蒙适配说明
- [environment.md](./environment.md) - 环境配置问题
- [ohos-application-compilation.md](./ohos-application-compilation.md) - 应用编译问题
- [ohos-run.md](./ohos-run.md) - 运行相关问题
- [permission-application.md](./permission-application.md) - 权限申请问题

## 参考链接

- [Flutter OH版本仓库](https://gitcode.com/openharmony-sig/flutter_flutter)
- [Flutter三方库适配计划](https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2)
- [DevEco Studio下载](https://developer.huawei.com/consumer/cn/develop)
- [OpenHarmony文档](https://docs.openharmony.cn/)