HarmonyOS中Flutter HAP包编译的常见问题
# HarmonyOS Flutter HAP包编译中的常见问题
## 1. 配置别名以简化构建命令
将以下别名添加到您的环境变量中，以便于开发：
*Windows*（通过 Git Bash）：
在文件资源管理器中右键点击 → <i>Git Bash Here</i>
*Linux/Mac*：编辑 `~/.bash_profile`，并通过 `source ~/.bash_profile` 将其添加到 `~/.zshrc`。
```
# 可选 --local-engine 用于自定义引擎构建（推荐在 Linux/Mac 上使用）
export ENGINE_DIR=~/ohos/engine
export ENGINE_DEBUG=$ENGINE_DIR/src/out/ohos_debug_unopt_arm64
export ENGINE_PROFILE=$ENGINE_DIR/src/out/ohos_profile_arm64
export ENGINE_RELEASE=$ENGINE_DIR/src/out/ohos_release_arm64
# 构建别名
alias fbuildD="flutter build hap --local-engine=$ENGINE_DEBUG --debug"
alias fbuildP="flutter build hap --local-engine=$ENGINE_PROFILE --profile"
alias fbuildR="flutter build hap --local-engine=$ENGINE_RELEASE --release"
# 运行别名
alias frunD="flutter run -d $(hdc list targets) --local-engine=$ENGINE_DEBUG --debug"
alias frunP="flutter run -d $(hdc list targets) --local-engine=$ENGINE_PROFILE --profile"
alias frunR="flutter run -d $(hdc list targets) --local-engine=$ENGINE_RELEASE --release"
```
*使用示例*：
```
flutter create hello --platforms ohos
cd hello
fbuildD # 构建调试版本
frunD # 运行调试版本
```
------
## 2. 安装后出现白屏
*错误日志*：
```
原因：信号：SIGSEGV(SEGV_MAPERR)@0x00000086e3272bf8
最后致命消息：线程：547846269584[致命：flutter/runtime/dart_vm_initializer.cc]
初始化 Dart VM 时出错：
快照版本错误，预期为 '8af474944053df1f0a3be6e6165fa7cf'
找到 'adb4292f3ec25074ca70abcd2d5c7251'
```
*原因*：引擎构建模式不匹配（例如，使用调试引擎构建发布版本）
*解决方案*：将引擎模式与构建标志匹配：
```
flutter run -d --debug # 调试模式
flutter run -d --release # 发布模式
flutter run -d --profile # 配置模式
```
------
## 3. 插件结构兼容性错误
*错误日志*：
```
糟糕；flutter 意外退出：
“类型 'Null' 不是类型 'List<dynamic>' 的子类型”。
```
*解决方案*：将 Flutter 更新到最新的主分支/开发分支（提交 45bd5e627e1 或更新版本）
------
## 4. `flutter pub get` 时的依赖冲突
*错误日志*：
```
因为 flutter_cache_manager >=3.0.0-nullsafety.0 <3.3.2 依赖于 path_provider...
版本解决失败。pub get 失败... 退出代码：1
```
*解决方案*：在 `pubspec.yaml` 中添加依赖覆盖：
```
dependency_overrides:
path_provider:
git:
url: https://gitee.com/openharmony-sig/flutter_packages.git
path: packages/path_provider/path_provider
path_provider_ohos:
git:
url: https://gitee.com/openharmony-sig/flutter_packages.git
path: packages/path_provider/path_provider_ohos
```
------
## 5. 未接受的 SDK 许可协议
*错误日志*：
```
hvigor 安装成功。
> hvigor 错误：原因：未接受 SDK 许可协议。
```
*原因*：项目使用 API 12 SDK，但项目结构为 API 11
*解决方案*：
1. 在 DevEco Studio 中：<i>迁移助手 → 5.0.0 → 迁移</i>
2. <i>文件 → 项目结构 → 兼容 SDK → 5.0.0(12)</i>
------
## 6. app.json 中版本重置
*问题*：在执行 `flutter build hap --release` 后，app.json 中的 `versionName` 重置为 1.0.0
*解决方案*：在构建命令中明确指定版本：
```
flutter build hap --build-name=4.0.3 --build-number=10000
```
查看原文
# Common Issues in Flutter HAP Package Compilation for HarmonyOS<p>## 1. Configuring Aliases to Simplify Build Commands<p>Add these aliases to your environment variables for streamlined development:<p>*Windows* (via Git Bash):
Right-click in File Explorer → <i>Git Bash Here</i>
*Linux/Mac*: Edit `~/.bash_profile` and add to `~/.zshrc` via `source ~/.bash_profile`<p>```
# Optional --local-engine for custom engine builds (recommended on Linux/Mac)
export ENGINE_DIR=~/ohos/engine
export ENGINE_DEBUG=$ENGINE_DIR/src/out/ohos_debug_unopt_arm64
export ENGINE_PROFILE=$ENGINE_DIR/src/out/ohos_profile_arm64
export ENGINE_RELEASE=$ENGINE_DIR/src/out/ohos_release_arm64<p># Build aliases
alias fbuildD="flutter build hap --local-engine=$ENGINE_DEBUG --debug"
alias fbuildP="flutter build hap --local-engine=$ENGINE_PROFILE --profile"
alias fbuildR="flutter build hap --local-engine=$ENGINE_RELEASE --release"<p># Run aliases
alias frunD="flutter run -d $(hdc list targets) --local-engine=$ENGINE_DEBUG --debug"
alias frunP="flutter run -d $(hdc list targets) --local-engine=$ENGINE_PROFILE --profile"
alias frunR="flutter run -d $(hdc list targets) --local-engine=$ENGINE_RELEASE --release"
```<p>*Usage*:<p>```
flutter create hello --platforms ohos
cd hello
fbuildD # Build debug version
frunD # Run debug version
```<p>------<p>## 2. White Screen After Installation<p>*Error Log*:<p>```
Reason:Signal:SIGSEGV(SEGV_MAPERR)@0x00000086e3272bf8
LastFatalMessage:Thread:547846269584[FATAL:flutter/runtime/dart_vm_initializer.cc]
Error while initializing the Dart VM:
Wrong full snapshot version, expected '8af474944053df1f0a3be6e6165fa7cf'
found 'adb4292f3ec25074ca70abcd2d5c7251'
```<p>*Cause*: Engine build mode mismatch (e.g., using debug engine with release build)
*Solution*: Match engine mode with build flags:<p>```
flutter run -d --debug # Debug mode
flutter run -d --release # Release mode
flutter run -d --profile # Profile mode
```<p>------<p>## 3. Plugin Structure Compatibility Error<p>*Error Log*:<p>```
Oops; flutter has exited unexpectedly:
"type 'Null' is not a subtype of type 'List<dynamic>' in type cast".
```<p>*Solution*: Update Flutter to latest master/dev branch (commit 45bd5e627e1 or newer)<p>------<p>## 4. Dependency Conflict During `flutter pub get`<p>*Error Log*:<p>```
Because flutter_cache_manager >=3.0.0-nullsafety.0 <3.3.2 depends on path_provider...
version solving failed. pub get failed... exit code: 1
```<p>*Solution*: Add dependency overrides in `pubspec.yaml`:<p>```
dependency_overrides:
path_provider:
git:
url: https://gitee.com/openharmony-sig/flutter_packages.git
path: packages/path_provider/path_provider
path_provider_ohos:
git:
url: https://gitee.com/openharmony-sig/flutter_packages.git
path: packages/path_provider/path_provider_ohos
```<p>------<p>## 5. Unaccepted SDK License Agreement<p>*Error Log*:<p>```
hvigor install success.
> hvigor ERROR: Cause: The SDK license agreement is not accepted.
```<p>*Cause*: Project uses API 12 SDK with API 11 project structure
*Solution*:<p>1. In DevEco Studio: <i>Migrate Assistant → 5.0.0 → Migrate</i>
2. <i>File → Project Structure → Compatible SDK → 5.0.0(12)</i><p>------<p>## 6. Version Reset in app.json<p>*Issue*: `versionName` in app.json resets to 1.0.0 after `flutter build hap --release`
*Solution*: Explicitly specify versions in build command:<p>```
flutter build hap --build-name=4.0.3 --build-number=10000
```