Flutter 鸿蒙宿主构建失败怎么查：沿 Hvigor 任务链找到第一处断点

“BUILD FAILED” 只是结尾，不是原因。Flutter 页面还没进入编译，鸿蒙宿主就提示插件无法加载；或者 HAP 已生成，团队却不确定本次到底选了哪个 product 和 buildMode。这样的故障如果只盯终端最后一行，排查往往会在 Dart、ArkTS、签名之间反复跳。更稳的方式是把 Hvigor 看成一个可查询的任务图，沿“环境 → 插件 → 任务 → 产物”找到第一个失败层。

本文围绕跨平台应援灯牌控制应用的 Flutter/OpenHarmony 宿主，讲清楚工程级与模块级任务入口、tasks/taskTree/buildInfo 各回答什么问题，以及如何保留足够的日志与产物信息。本文使用的示例工程仍是 OpenHarmony API 20 基线；命令示例依据官方 Hvigor 文档，读者升级到 HarmonyOS API 26 前必须先核对自己平台的 wrapper 版本与 Flutter 插件兼容性。

1. 先找任务入口，而不是先看业务页面

在这个工程里，ohos/hvigorfile.ts 是工程级入口，ohos/entry/hvigorfile.ts 是 entry 模块入口。前者挂接 Flutter 插件，后者使用内置 HAP 任务。它们并不是两份重复配置：一个确定“工程如何认识 Flutter”，另一个确定“模块如何生成 HAP”。

// ohos/hvigorfile.ts，保留与问题有关的部分
import path from 'path'
import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { flutterHvigorPlugin } from 'flutter-hvigor-plugin';

export default {
  system: appTasks,
  plugins: [flutterHvigorPlugin(path.dirname(__dirname))]
}

这里 appTasks 是系统任务入口，flutterHvigorPlugin(...) 是跨端桥接。如果构建输出在插件装载阶段失败，尚未执行 HAP 任务；此时去改 entry 页面没有因果关系。path.dirname(__dirname) 传的是 Flutter 工程根目录，插件包本身的加载位置还要看依赖配置。

2. 模块级 hapTasks 的职责不要写错

entry 模块入口非常短：

// ohos/entry/hvigorfile.ts，示例工程现状
import { hapTasks } from '@ohos/hvigor-ohos-plugin';

export default {
  system: hapTasks,
  plugins: []
}

hapTasks 提供模块构建链路；当前模块没有额外挂入自定义插件。读者若看到“找不到 assembleHap”一类报错，应先确定 wrapper、模块名称和任务是否成功注册，再考虑编译器问题。相反，若日志已经进入 ArkTS 编译任务，问题才可能落在源码、资源或 API 版本。判断依据是日志中的最早错误及其前一阶段，而非故障发生时最后一个可见的文件名。

3. file: 插件依赖是任务图的前置条件

示例工程通过 ohos/package.json 引用本机 Flutter SDK 中的 Hvigor 插件。下面将具体磁盘位置脱敏，只展示依赖形式；读者不要复制示意目录。

{
  "dependencies": {
    "flutter-hvigor-plugin": "file:D:\\SDK\\flutter_ohos\\packages\\flutter_tools\\hvigor"
  }
}

这种写法使“插件目录存在”成为任务注册的前置条件。迁移电脑或 CI 时，即使 flutter --version 正常，file: 指向的目录若不存在，Hvigor 也不能装载 Flutter 插件。可以在项目根目录用只读检查确认：

$spec = (Get-Content .\ohos\package.json -Raw |
  ConvertFrom-Json).dependencies.'flutter-hvigor-plugin'
if (-not $spec.StartsWith('file:')) { throw '依赖类型需要重新核对' }
$pluginPath = $spec.Substring(5)
Test-Path -LiteralPath $pluginPath

True 只能证明目录存在，不能证明版本兼容；False 则足以解释为什么插件装载失败。不同项目可能使用 ohpm 依赖、工作区相对路径或另一套 Flutter fork，不应把本例的 file: 形式当成通用规范。

4. 用三个查询命令把任务图读出来

官方 hvigorw 命令行指南 列出 tasks、taskTree 与 buildInfo。它们不是三个“再试一次”的构建命令，而是三种不同的询问。执行前要确认目标工程有可用的 hvigorw 或已安装对应命令行工具；除了版本/帮助命令，其余任务应在构建工程根目录执行。

hvigorw tasks
hvigorw taskTree
hvigorw buildInfo

命令	回答的问题	适合定位
tasks	当前工程/模块注册了哪些任务	插件或模块任务是否出现
taskTree	一个任务依赖哪些前置任务	为什么日志在此任务之前失败
buildInfo	product、module、target、buildMode 如何解析	产物为什么不是预期变体

如果 tasks 都无法运行，先回到工具与插件装载；如果 tasks 正常而某目标任务不存在，再核对任务名称和构建插件；若任务树正确而编译失败，才向源码层移动。查询结果最好连同工具版本保存，避免以后用另一台机器复现时任务图已经变化。

5. 把 product、module、target 和 buildMode 说清

“构建 entry 的 release HAP”应对应明确参数，而不是依赖 IDE 上一次选中的状态。官方命令行示例采用模块模式、产品、模块目标和构建模式组合：

hvigorw --mode module `
  -p product=default `
  -p module=entry@default `
  -p buildMode=release `
  assembleHap

这段是官方语法的操作示例，不是本文对该 Flutter/OpenHarmony 工程 API 26 的实测命令。运行前先用 buildInfo 确认项目里确实有 default product 与 entry@default target，再检查当前 Hvigor 版本支持这些参数。release 是构建模式选择，但最终是否可用于发布，还依赖签名、调试标记、渠道配置和产物核验；不能从任务名推断“已经上架可用”。

6. 保留首错、堆栈与构建上下文

只给同事发送最后一行 BUILD FAILED，几乎没有定位价值。可以在项目根目录执行时将完整输出保存；以下脚本只展示日志采集方法，运行环境与命令名称仍需按项目确认。

$log = Join-Path (Get-Location) 'hvigor-assembleHap.log'
hvigorw --mode module -p product=default `
  -p module=entry@default -p buildMode=debug `
  assembleHap --stacktrace *>&1 | Tee-Object -FilePath $log
Write-Output "exit code: $LASTEXITCODE"

日志里的第一处错误往往早于失败摘要。保存时应一起记下 hvigorw --version、Node、IDE/SDK 精确版本，以及本次 product/target/buildMode。若命令行没有进入 task 阶段，优先检查环境和依赖；若 PackageHap 之后才失败，再查签名和打包输入。不要因为某个任务显示 UP-TO-DATE 就误判它“已重新执行”：官方 任务说明 将其定义为增量跳过标志。

7. 产物是否属于本次构建，要额外证明

项目以前构建过时，输出目录可能残留旧 HAP。命令成功与“拿到正确的新包”之间还需要一层核对：文件时间、大小、哈希、产品和模块信息。下列命令适合在构建结束后做只读清单：

Get-ChildItem . -Recurse -Filter *.hap |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 10 FullName, Length, LastWriteTime

这一步能识别是否真的出现新文件，却不能替代包信息与签名核验；后者要使用对应 SDK/渠道的工具，并和应用配置逐项比对。若找不到 HAP，回到任务日志中 assembleHap 的实际执行结果；若只找到旧文件，不要把“任务 UP-TO-DATE”直接翻译为“发布包已更新”。

8. 根据症状建立排查分叉

首个现象	更可能的断点	有效动作
file: 依赖路径不存在	插件装载之前	修正本机 SDK 路径，重新解析依赖
tasks 命令本身不可用	wrapper/命令行环境	核对安装平台、PATH 与官方版本表
tasks 有输出但没有目标任务	插件注册或任务名称	查两级 hvigorfile.ts 和插件文档
taskTree 正常、编译器报错	源码/资源/API	定位首个编译错误及版本边界
任务完成但 HAP 没更新	增量构建/产物路径	核对输入输出、文件时间和日志
HAP 存在但设备拒装	签名/设备兼容	查包信息、签名、设备日志

这张表强调“第一断点”而不是“最后症状”。构建层和运行层分开以后，团队能避免为了一个签名问题修改 Flutter 状态管理，也能避免因一个本地插件路径错误去升级整个 SDK。

9. 何时该考虑自定义任务

Hvigor 官方提供自定义任务与插件机制，但不是每个项目都需要。现有工程已通过 Flutter 插件和内置 hapTasks 构成任务链；若只是想收集版本、日志和产物，外部脚本可能更简单。只有当步骤必须参加构建依赖关系、需要明确输入输出和增量执行时，才考虑注册任务，并先阅读官方 任务开发 与 插件开发 文档。

盲目添加“万能检查任务”会扩大升级风险：插件 API 可能随平台工具链变化，且新任务若没有正确声明输入输出，增量构建结果也可能不可信。本文的处理范围止于读懂并排查既有任务图，不改现有宿主构建脚本。

10. 可复现验收清单

1. 工程级 appTasks、模块级 hapTasks 与 Flutter 插件来源有文件证据。
2. 本地 file: 依赖在目标机器上存在，插件版本与当前工具链兼容性已确认。
3. tasks、taskTree、buildInfo 输出已保存，能够指向具体 product/target。
4. 构建日志保留首个异常、完整堆栈、命令参数和退出码。
5. HAP 的时间、大小、哈希及包信息对应本次构建，而不是旧缓存。
6. 安装和业务运行另列结果；构建成功不代替设备验证。

Hvigor 的价值不只是“执行打包”。它给了我们可观察的任务链：先问任务是否注册，再问依赖是否满足，最后核对产物是否真实更新。沿这个顺序排查，构建失败就不再是一句没有上下文的红字。