使用 Flutter 命令行编译构建应用报错

问题现象

使用 flutter build hap --release 命令行编译构建应用的时候报错

> hvigor ERROR: ENOENT: no such file or directory, stat `xxx\ohos\entry\oh_modules\flutter_native_x86_64`

问题根因

调试阶段有交替使用模拟器和真机设备，使用了模拟器的缓存

解决方案

1. 编译构建命令指定平台架构

   flutter build hap --release --target-platform ohos-arm64
   

2. 手动删除项目里以下缓存文件

   ohos/
   ├── .dart_tool 
   ├── .build
   ├── ohos
   │   ├── entry/
   │   │   ├── build
   │   │   ├── oh_modules
   │   └─ oh_modules
   

   重新执行编译构建命令 flutter build hap --release

拷贝或克隆其他 Flutter OH 项目到本地后无法运行

问题现象

从其他开发者或 Git 仓库拷贝/克隆 Flutter 项目后，编译运行时报错

排查步骤

• 检查 Flutter OH 项目与本地 Flutter版本的兼容性

  打开项目 pubspec.yaml 文件，查看 sdk版本

  environment:
    sdk: '版本号'
  

  终端执行 flutter doctor 查看本地 Flutter 环境版本，看是否和项目版本兼容，若不兼容需修改。

• 删除 pubspec.lock 并重新获取依赖

  # Windows
  del pubspec.lock
  # macOS/Linux
  rm pubspec.lock
  
  flutter clean
  flutter pub get
  

  说明：pubspec.lcok 是依赖锁定文件，原项目的环境可能与你本地不同，删除后让 pub 根据当前环境重新解析依赖版本。

• 清理构建缓存

  flutter clean
  

  删除 build/ , dart_tool/, ohos/oh_modules, ohos/entry/build 等缓存目录。

配置别名，简化日常开发的编译命令

在环境变量配置文件中配置别名，简化Flutter OpenHarmony化日常使用的命令：

• windows, 使用 Git Bash 可以执行常见的linux命令。(使用方式：鼠标右键点击文件管理器中的空白处，左键点击 Git Bash Here)
• linux, 修改 ~/.bash_profile。
• mac, 修改 ~/.bash_profile, 并在 ~/.zshrc 中加上 source ~/.bash_profile。

# --local-engine 参数可选，指向自行编译的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工程目录中即可使用别名编译或运行。

flutter create hello --platforms ohos
cd hello
# 编译debug版本
fbuildD
# 运行debug版本
frunD

应用编译成功，安装后出现白屏的情况

详见 ohos运行相关问题

应用编译报错，flutter插件结构重构前的版本使用了重构后的插件库

报错日志:

Oops; flutter has exited unexpectedly: "type 'Null' is not a subtype of type 'List<dynamic>' in type cast".

解决方案:
flutter_flutter更新到master或dev的最新版本。(45bd5e627e1f1e5f4d335f205781565f576acc60, 2024-05-10)

Flutter编译插件时引入预编译so包，so包未打入har包

问题现象：

使用DevEco工具查看编译后的har包目录下未找到引入的so包，导致功能调用异常

问题分析：

so包放置的路径不对导致编译时未打入har包

解决方案:

可参考FFI插件开发文档中关于预编译so包的放置路径

flutter pub get 依赖冲突报错

报错日志：

Resolving dependencies...
Because flutter_cache_manager >=3.0.0-nullsafety.0 <3.3.2 depends on path_provider from hosted and flutter_cache_manager depends on path_provider from git, flutter_cache_manager >=3.0.0-nullsafety.0 <3.3.2 forbidden.
So bedause xxx depends on flutter_cache_manager 3.3.1, version solving failed.
pub get failed
...
exit code: 1

解决方案：

使用 dependency_overrides 消除依赖冲突。

dependencies:
  flutter:
    sdk: flutter
dependency_overrides:
  path_provider:
    git:
      url: https://gitcode.com/CPF-Flutter/flutter_packages.git
      path: packages/path_provider/path_provider
  path_provider_ohos:
    git:
      url: https://gitcode.com/CPF-Flutter/flutter_packages.git
      path: packages/path_provider/path_provider_ohos

flutter三方库依赖错误

日志信息：

Error:error:AbiSpecificInteger'Int32' is missing mapping for 'ohos_arm64'.
Dart snapshot generator failed with exit code 254
Target ohos_aot_profile_ohos-arm64 failed: Exception: AOT snapshotter exited with code 254.

问题分析：这类报错一般是未使用OpenHarmony社区适配的三方库

解决方案：查看yaml文件的三方库依赖，通过文档查找对应的三方库地址OpenHarmony平台已适配三方库

The SDK license agreement is not accepted

日志信息:

hvigor install success.
> hvigor ERROR: Cause: The SDK license agreement is not accepted.

问题分析：ohos工程的结构还是api11的，但是使用的sdk是api12的，这种情况下就会出现这个报错信息。

解决方案：将ohos工程结构升级为api12。

操作步骤：

1. DevEco-Studio -> Migrate Assistant -> 5.0.0 -> Migrate
2. DevEco-Studio -> File -> Project Structure -> Compatible SDK -> 5.0.0(12)

通过flutter build hap -release 编译版本 会导致 app.json versionName 字段重置

背景：
查看app.json 下的versionName 字段，然后执行flutter build hap -release 编译版本进行出包。

现象：发现次字段 再次被重置1.0.0。

原因：当前规格，目前默认build会使用这个版本号。

解决：需要指定versionName和versionCode可以在build指令时加上指定版本。

参考：flutter build hap --build-name=4.0.3 --build-number=10000

应用编译报错flutter工程和依赖的插件工程不是在同一个磁盘

日志信息:

ohpm ERROR: Found exception: xxx is not in the same file system as the current project, reached retry limit or non retryable error encountered.

问题分析：flutter工程和依赖的插件工程不是在同一个磁盘，这种情况下就会出现这个报错信息。

解决方案：Windows环境下flutter工程和依赖的插件工程需要在同一个磁盘。

Note that you need plugins to import files that are not JavaScript

日志信息:

> hvigor ERROR: Failed :entry:default@CompileArkTS...
> hvigor ERROR: Unexpected token (Note that you need plugins to import files that are not JavaScript)

问题分析：DevEco Studio由低版本升级到高版本，这种情况下就会出现这个报错信息。

解决方案：

修改 hvigor-config.json5 配置文件：

{ 
  "modelVersion": "5.0.0",
  "dependencies": {
  },
  "properties": {
    "ohos.nativeResolver": false
  }
}

DevEco工具同步或者运行Flutter新模板工程依赖的插件与SDK不在一个磁盘

日志信息

> hvigor ERROR: The srcPath is not a relative path: xxxx

* Try the following:
> Make sure the srcPath in the hvigorconfig.ts file of the project is a relative path.

问题分析：新模板工程编译构建中，flutter-hvigor-plugin插件使用hvigorConfig.includeNode添加三方库源码作为节点，relativePath无法生成跨磁盘的相对路径，导致传入的参数srcPath为绝对路径。

解决方案：应用编译报错flutter工程和依赖的插件工程不是在同一个磁盘