鸿蒙flutter 环境配置
[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/)
~ END ~