同一个 Flutter 计数器,两个 HAP 都能编译出来。第一个包传进 Windows 上的鸿蒙模拟器,安装停在 9568347。第二个包能安装并拉起页面,点一次加号,数字从 0 跳到 1。两次构建的 Flutter 源码、调试模式和签名选项相同,变化的是 --target-platform。

这篇记录对应 Flutter 鸿蒙版的 Issue #IBGRV9。帖子里的安装日志已经打印出 install parse native so failed,讨论随后指向模拟器和 Flutter 原生库的架构。这里在较新的 API 24 模拟器里重新做一遍,看看除了换参数,还能用哪些证据把原因定位到安装包。

1. 先认出失败发生在哪一步

原 Issue 在 HAP 上传后,由设备安装命令返回错误。日志已经指到解析原生库的阶段,接下来查设备 ABI 和 HAP 里的 Flutter 引擎。

复现用的是 Windows、DevEco Studio 6.1.1.460、Flutter 鸿蒙版 3.35.8-ohos-1.0.3 和 Dart 3.9.2。模拟器系统为 HarmonyOS API 24,使用 SDK 自带的 HDC。工程由 flutter create --platforms ohos --org com.ohosnotes abi_probe 生成,保留计数器页面,包名是 com.ohosnotes.abi_probe。保留简单的有状态页面,是为了最后能验证 Flutter 渲染和按钮响应。

先查本次连接的设备和设备端报告的 ABI:

hdc list targets -v
hdc -t 127.0.0.1:5555 shell param get const.product.cpu.abilist

第二条返回 x86_64。构建前先把这个值记下来,后面可以直接和包里的库目录做对照。如果 HDC 同时列出设备和模拟器,安装与启动也要指定同一个目标,否则设备属性和运行截图可能来自两个不同设备。

2. 让 ARM64 包重现错误

flutter build hap --debug --target-platform ohos-arm64 --no-codesign
Copy-Item build/ohos/hap/entry-default-unsigned.hap ./arm64.hap
hdc -t 127.0.0.1:5555 install .\arm64.hap

构建结束时生成了 HAP。安装时的可定位信息是:

code:9568347 error: install parse native so failed.
In the module named entry, the Abi type supported by the device does not
match the Abi type configured in the C++ project.

上面按行换行便于阅读。这里的 entry 属于应用主模块。即使业务只有 Dart 和界面组件,Flutter 引擎也会以 .so 随包交付,所以创建模板时有没有写 C++ 与这个错误可以同时成立。安装日志已经指出 ABI 方向,下一步直接检查交付物,比调整 Dart 代码更快。

HAP 可以按 ZIP 容器读取。只看到 libs/x86_64 目录还缺一层证据,因为目录名由打包过程决定。这里直接读 libflutter.so 头部偏移 18、19 处的两个字节,按小端序解出 e_machine。已在两份实测 HAP 上验证,运行脚本只需要 PowerShell 和 .NET。 ELF 架构编号表

Add-Type -AssemblyName System.IO.Compression.FileSystem
function Get-FlutterHapAbi([string]$Path) {
    $zip = [IO.Compression.ZipFile]::OpenRead((Resolve-Path $Path).Path)
    try {
        $engines = @($zip.Entries | Where-Object {
            $_.FullName -match '^libs/[^/]+/libflutter\.so$'
        })
        if (!$engines) { throw "HAP 内没有找到 libflutter.so" }
        foreach ($engine in $engines) {
            $reader = [IO.BinaryReader]::new($engine.Open())
            try { $header = $reader.ReadBytes(20) }
            finally { $reader.Dispose() }

            if ($header.Length -ne 20 -or
                [BitConverter]::ToString($header, 0, 4) -ne '7F-45-4C-46' -or
                $header[4] -ne 2 -or $header[5] -ne 1) {
                throw "需要小端 ELF64:$($engine.FullName)"
            }
            $machine = [int]$header[18] + 256 * [int]$header[19]
            $abi = switch ($machine) {
                62  { 'x86_64' }
                183 { 'arm64-v8a' }
                default { "unknown ($machine)" }
            }
            [pscustomobject]@{
                Entry = $engine.FullName
                Machine = $machine
                ElfAbi = $abi
                DirectoryMatches = ($engine.FullName.Split('/')[1] -ceq $abi)
            }
        }
    } finally {
        $zip.Dispose()
    }
}

两份 HAP 都构建完成后,按以下顺序跑检查。先确认目录和 ELF 一致,再看设备支持的 ABI 是否包含该引擎的 ABI。

$deviceAbis = ([string](hdc -t 127.0.0.1:5555 shell param get const.product.cpu.abilist)).Trim() -split ',\s*'
foreach ($hap in './arm64.hap', './x64.hap') {
    Get-FlutterHapAbi $hap | Select-Object Entry, Machine, ElfAbi,
        DirectoryMatches, @{Name='DeviceSupports'; Expression={$_.ElfAbi -in $deviceAbis}}
}

实际读取到 183 和 62,两者的 DirectoryMatches 都是 True。设备只报告 x86_64,所以第一个包的 DeviceSupports 是 False,第二个才是 True。如果在打包参数里看到了 ohos-x64,实际读出的仍是 183,先对照安装命令的路径和包的修改时间,确认使用的是刚生成的文件。

3. 同一工程改打 x64 包

flutter build hap --debug --target-platform ohos-x64 --no-codesign
Copy-Item build/ohos/hap/entry-default-unsigned.hap ./x64.hap
hdc -t 127.0.0.1:5555 install .\x64.hap
hdc -t 127.0.0.1:5555 shell aa start -a EntryAbility -b com.ohosnotes.abi_probe -m entry

构建输出路径相同,第一次构建结束后先复制出 ARM64 包,第二次再复制出 x64 包。这样能保留两份证据,也避免敲完新命令后,安装时又指向旧目录残留的 HAP。两轮都使用了 --no-codesign,安装测试只覆盖这台本地开发模拟器。

对照项ARM64 包x64 包
编译目标ohos-arm64ohos-x64
调试 HAP已生成已生成
包内引擎libs/arm64-v8a/libflutter.solibs/x86_64/libflutter.so
ELF 头部的 e_machine183(AArch64)62(x86-64)
x86_64 模拟器安装返回 9568347install bundle successfully
启动和页面交互安装被拒绝能启动,计数 0 → 1

x64 包启动后显示计数 0,点击右下角加号验证交互

图 1 x64 包启动后显示计数 0,点击右下角加号验证交互。

点击一次后,Flutter 计数器显示 1

图 2 点击一次后,Flutter 计数器显示 1。

4. 遇到同类错误时先查哪一层

Issue 的后续讨论 里的另一个问题是 ohos-x64 被工具判为无效参数。它发生在构建开始前,可以用 flutter --version 和 flutter build hap --help 核对 SDK,再对照 x64 支持变更。

已看到的现象下一步
Flutter 拒绝 ohos-x64确认终端所用 SDK 和构建参数
HAP 已生成,目录或 ELF 与目标架构对不上检查安装路径、旧产物和构建目标
Flutter 引擎架构匹配,安装仍报 9568347查日志指出的模块,对该模块的其他原生库做相同检查
安装通过,启动后页面异常切到启动和运行日志,查看实际失败点

5. 用 SDK 工具交叉核对安装包

工程已经装了 DevEco Studio 时,可以用 SDK 附带的 llvm-readelf 再读一遍。这次只取 HAP 里的引擎文件,就能看到 Class 和 Machine 两个字段。下面在保存了两份 HAP 的目录执行,以 x64 包为例。

$tool = 'default/openharmony/native/llvm/bin/llvm-readelf.exe'
$readelf = Join-Path $env:DEVECO_SDK_HOME $tool
tar.exe -xf ./x64.hap libs/x86_64/libflutter.so
& $readelf -h ./libs/x86_64/libflutter.so |
    Select-String 'Class:|Machine:'
Get-FileHash ./arm64.hap, ./x64.hap -Algorithm SHA256
安装文件LLVM 读取结果本次 SHA-256 前 12 位
arm64.hapELF64,AArch6467368d59dbbb
x64.hapELF64,Advanced Micro Devices X86-6455728186dd0f

两种方法读到的架构一致。哈希用来区分这次的两个产物,方便回头核对 IDE 输出和 HDC 日志里实际安装的路径。换一台机器重新构建时,记录自己的完整哈希即可。遇到「明明切到 x64,装上去还是报旧错」时,先从本次安装日志找到 HAP 路径,再对那个文件算哈希和读 ELF。这样可以把「构建了哪个包」和「设备收到哪个包」分别核实。

这次的排查顺序适用于类似的安装失败。先找到设备报告的 ABI,再从安装文件里读出原生库的架构,最后用同一设备验证新的包。对于带多个原生库的工程,保留失败模块和实际文件名,逐个验证,排查结果就能直接附到 Issue 讨论里。

示例源码

AtomGit 示例仓库。本篇工程在 abi_probe 目录,README 内有构建和复现命令。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐