当前位置：首页 > news >正文

HarmonyOS ArkTS API 24+ 实战：构建、安装并验证 M1 首个可运行版本

news 2026/7/26 6:09:35

一、能看到页面不等于完成验证

前几篇已经完成了 M1 的首页、五项导航、数据模型和组件拆分。此时在 DevEco Studio 中看到页面，只能说明某一次运行路径成功，还不能回答下面几个问题：

ArkTS 类型检查是否通过；
Hvigor 是否真正生成了 HAP；
HAP 是否安装到了目标模拟器；
应用是否能启动并保留正确的导航状态；
API 26 Beta SDK 编译、API 24 模拟器运行和“API 24 全面兼容”是否是同一件事。

这一篇把 M1 的构建脚本、安装检查、交互验证和版本口径整理成一条可复现流程。下文只报告测试实际观察到的结果，不把局部运行扩大成完整兼容认证。

二、先明确本次验证口径

M1 测试报告中的环境信息如下：

项目	本次实际值
编译工具	DevEco Studio Beta 26.0.0.461 内置 Hvigor
编译 SDK	HarmonyOS SDK API 26 Beta1，版本 26.0.0.23
运行设备	HarmonyOS API 24 模拟器
设备 API	24
应用	`com.atan.enotebook`
验证范围	安装、启动、首页首屏和五项导航

因此本文采用这样的准确表述：M1 使用 API 26 Beta SDK 构建成功，并在一个 API 24 模拟器中完成安装、启动和指定交互检查。

这不等同于“使用 API 24 SDK 编译成功”，也不等同于“整个 App 已经完成 API 24 全面兼容”。编译 SDK、兼容目标、运行设备和业务覆盖范围需要分别说明。

三、构建脚本先固定工具链

项目根目录中的build.ps1负责调用 DevEco Studio 安装目录里的 Hvigor：

$ErrorActionPreference='Stop'$projectRoot=Split-Path-Parent$MyInvocation.MyCommand.Path$devecoRoot=$env:DEVECO_STUDIO_HOMEif([string]::IsNullOrWhiteSpace($devecoRoot)){throw'DEVECO_STUDIO_HOME is not configured'}$hvigor=Join-Path$devecoRoot'tools\hvigor\bin\hvigorw.bat'$nodeHome=Join-Path$devecoRoot'tools\node'$javaHome=Join-Path$devecoRoot'jbr'$sdkHome=Join-Path$devecoRoot'sdk'

1. 为什么先设置 Stop

$ErrorActionPreference = 'Stop'让 PowerShell 在遇到错误时立即停止。构建脚本不应该在 Hvigor 失败后继续执行，并给出看起来像成功的后续输出。

2. 为什么用脚本自身目录作为工程根

$MyInvocation.MyCommand.Path表示当前脚本文件路径，Split-Path -Parent取得脚本所在目录。这样从其他工作目录执行build.ps1时，脚本仍然能回到正确的工程根，而不是依赖调用者当前所在目录。

3. DevEco 路径需要按本机调整

公开文章中不直接写入某台电脑的安装绝对路径，而是通过DEVECO_STUDIO_HOME环境变量传入 DevEco Studio 根目录。复制到其他电脑时，只需要把这个环境变量设置为本机安装目录，脚本的其余路径拼接逻辑可以保持不变。

四、检查工具路径是否存在

脚本继续检查 Hvigor、Node.js、Java 和 SDK 目录：

foreach($requiredPathin @($hvigor,$nodeHome,$javaHome,$sdkHome)){if(-not(Test-Path-LiteralPath$requiredPath)){throw"Required DevEco path was not found:$requiredPath"}}

这段检查放在构建前面很有必要。若直接调用不存在的脚本，PowerShell 报错信息通常只能说明命令失败；现在可以明确告诉开发者是哪个工具路径缺失。

Test-Path -LiteralPath按字面检查路径，不会把路径中的特殊字符当成通配模式。路径检查通过后，才进入环境变量配置和 Hvigor 执行阶段。

五、固定 Java、Node 和 SDK 环境

$env:NODE_HOME =$nodeHome$env:JAVA_HOME =$javaHome$env:DEVECO_SDK_HOME =$sdkHome$env:Path ="$javaHome\bin;$nodeHome;$env:Path"

DevEco Studio 自带的 Java、Node 和 SDK 需要与当前 Hvigor 工具链匹配。如果机器同时安装了其他 Java 或 Node 版本，直接使用系统环境变量可能出现“IDE 中能运行，命令行失败”的差异。

这里把 IDE 目录中的工具放到当前 PowerShell 进程的环境变量中，Hvigor 子进程会继承这些值。Path把 Java 和 Node 的 bin 目录放在前面，减少被系统其他版本优先命中的可能。

六、在正确目录执行 assembleHap

Push-Location$projectRoottry{&$hvigor--mode module-p module=entry@default-p product=default assembleHapif($LASTEXITCODE-ne0){throw"Hvigor failed with exit code$LASTEXITCODE"}}finally{Pop-Location}

1.`Push-Location`和`Pop-Location`

构建前切换到工程根目录，构建结束后无论成功还是失败都恢复调用者原来的目录。finally能保证清理动作执行，减少脚本对当前终端环境的副作用。

2.`--mode module`

当前命令按模块模式执行，并通过-p module=entry@default指定 Entry 模块和 default 变体。-p product=default指定产品配置，最后的assembleHap负责完成编译和 HAP 组装。

3. 为什么检查`$LASTEXITCODE`

外部批处理程序的失败状态通过$LASTEXITCODE返回。即使 PowerShell 没有抛出普通异常，也要检查这个退出码，否则 Hvigor 失败后脚本可能继续结束，让调用方误以为构建成功。

七、执行构建和查看产物

在工程根目录执行：

.\build.ps1

本次测试的关键结果是：

检查项	结果
ArkTS 类型检查	通过，输出包含`TYPE CHECK SUCCESSFUL`
HAP 构建	通过，输出包含`BUILD SUCCESSFUL`
HAP 产物	`entry-default-unsigned.hap`非空
应用签名	尚未配置正式签名，当前为 unsigned HAP

构建成功后，产物位于 Entry 模块的 default 输出目录。调试阶段生成 unsigned HAP 可以用于当前模拟器检查，但正式上架、真机分发和持续交付仍需要配置签名。

八、安装和启动不是构建的附属步骤

HAP 生成后，还要检查它是否真的进入目标设备并能启动。M1 测试报告确认了：

模拟器中存在com.atan.enotebook；
Bundle 元数据中的compileSdkVersion为26.0.0.23；
设备 API 为 24；
EntryAbility能够启动；
首页首屏能显示标题、四个指标、三条待办和底部导航。

这几项分别覆盖了安装存在性、构建元数据、运行设备、入口能力和首屏内容。只看到构建日志中的BUILD SUCCESSFUL，不能替代安装和启动检查。

九、五项导航如何验证

M1 通过点击底部页签并检查页面标题和选中态完成交互验证：

页签 ID	页面文字	预期行为	结果
`home`	注塑工程师助手	展示首页看板，首页高亮	通过
`machines`	机台	展示机台占位页，机台高亮	通过
`debug`	调机	展示调机占位页，调机高亮	通过
`exceptions`	异常	展示异常占位页，异常高亮	通过
`reports`	报表	展示报表占位页，报表高亮	通过

这项测试同时覆盖 D-004 和 D-006 中的导航配置、Store、@State、@Link和条件渲染。非法页签 ID 的情况由代码检查确认：Store 会保留上一个合法状态。

4. 一次验证的执行顺序

为了让结果容易复现，建议把一次 M1 检查固定成“构建、安装、启动、首屏、交互、截图”六步。构建阶段确认类型检查和 HAP 产物，安装阶段确认应用包存在，启动阶段确认EntryAbility能打开，首屏阶段检查指标和待办，交互阶段逐项点击五个页签，最后保存能对应到测试步骤的截图。

如果某一步失败，不要直接把错误归因于 API 版本。先记录失败发生在工具链、HAP、设备连接、页面渲染还是交互状态，再对照对应层的日志和代码。分层记录能避免把构建问题、安装问题和业务 UI 问题混在一起排查。

十、运行截图和视觉检查

首页截图显示四张指标卡、三条现场待办和底部导航：

图 1：当前工程在 API 24 模拟器中的首页首屏，首页沿用 M1 形成的布局与数据链路。

切换调机页签后，正文显示占位内容，底部导航选中态同步变化：

图 2：M1 调机页签的状态联动结果。

人工检查结果包括：首页没有横向溢出，指标卡没有相互覆盖，底部导航没有遮挡正文，调机页签标题和选中态一致。

十一、哪些结论现在不能写

当前证据支持的结论是：

M1 ArkTS 源码通过当前编译器检查；
API 26 Beta SDK 构建成功并生成 HAP；
HAP 在一个 API 24 模拟器中安装、启动并完成指定交互检查；
首页和五项导航达到 M1 的首个可运行版本标准。

当前证据不支持以下扩大表述：

API 24 SDK 编译链路已经验证；
所有 HarmonyOS 设备形态都兼容；
机台、调机、异常和报表业务已经完成；
已经具备数据库、网络、离线缓存和正式签名能力。

技术文章把边界写清楚，读者才能按相同条件复现结果，也能知道下一轮测试还缺少什么。

十二、构建配置与脚本的对应关系

构建脚本只能调用工具，工程配置则决定产品、模块和目标设备如何参与构建。下面是当前 M1 相关的build-profile.json5结构：

{ "app": { "signingConfigs": [], "products": [ { "name": "default", "compatibleSdkVersion": "6.1.1(24)", "targetSdkVersion": "26.0.0", "runtimeOS": "HarmonyOS", "buildOption": { "strictMode": { "caseSensitiveCheck": true, "useNormalizedOHMUrl": true } } } ], "buildModeSet": [ { "name": "debug" }, { "name": "release" } ] }, "modules": [ { "name": "entry", "srcPath": "./entry", "targets": [ { "name": "default", "applyToProducts": ["default"] } ] } ] }

这里有三个容易混淆的版本字段。compatibleSdkVersion表达产品兼容目标，targetSdkVersion表达目标 API 版本，实际编译使用的 SDK 则由 DevEco 工具链和 SDK 安装环境决定。三者不能在文章中混写成一个“API 版本”。

当前测试报告确认的是 API 26 Beta SDK 编译成功、API 24 模拟器运行观察完成。配置中的兼容目标不能单独证明所有 API 24 功能都已经完成编译和兼容验证。

十三、完整构建脚本参考

为了便于初学者复制检查，下面给出构建脚本的完整版本。公开文章使用环境变量表达 DevEco 根目录，不绑定某台电脑的个人安装路径。

$ErrorActionPreference='Stop'$projectRoot=Split-Path-Parent$MyInvocation.MyCommand.Path$devecoRoot=$env:DEVECO_STUDIO_HOMEif([string]::IsNullOrWhiteSpace($devecoRoot)){throw'DEVECO_STUDIO_HOME is not configured'}$hvigor=Join-Path$devecoRoot'tools\hvigor\bin\hvigorw.bat'$nodeHome=Join-Path$devecoRoot'tools\node'$javaHome=Join-Path$devecoRoot'jbr'$sdkHome=Join-Path$devecoRoot'sdk'foreach($requiredPathin @($hvigor,$nodeHome,$javaHome,$sdkHome)){if(-not(Test-Path-LiteralPath$requiredPath)){throw"Required DevEco path was not found:$requiredPath"}}$env:NODE_HOME =$nodeHome$env:JAVA_HOME =$javaHome$env:DEVECO_SDK_HOME =$sdkHome$env:Path ="$javaHome\bin;$nodeHome;$env:Path"Push-Location$projectRoottry{&$hvigor--mode module `-p module=entry@default `-p product=default ` assembleHapif($LASTEXITCODE-ne0){throw"Hvigor failed with exit code$LASTEXITCODE"}}finally{Pop-Location}

读这段脚本时不要只关注最后的assembleHap。前面的路径检查决定命令是否能找到工具，环境变量决定 Hvigor 使用哪套 Java、Node 和 SDK，Push-Location决定相对路径从哪里解析，$LASTEXITCODE决定失败是否会被明确抛出。构建命令只是整条链路的最后一步。

十四、从构建到运行的证据链

一次完整验证可以拆成以下证据层：

14.1 类型检查证据

构建输出出现TYPE CHECK SUCCESSFUL，说明当前源码通过了本次工具链的 ArkTS 类型检查。它证明的是编译器接受当前代码，不代表代码已经覆盖所有业务输入和设备形态。

14.2 HAP 产物证据

构建输出出现BUILD SUCCESSFUL，并生成非空的entry-default-unsigned.hap，说明模块已经完成组装。HAP 是可安装的应用包，但当前没有正式签名，不能直接当作发布包。

14.3 设备安装证据

安装后需要确认设备中存在com.atan.enotebook，并确认启动 Ability 能够加载pages/Index。如果构建成功但设备中没有应用，问题可能发生在安装命令、设备连接或包标识，而不是页面代码。

14.4 UI 运行证据

启动后检查首页标题、四项指标、三条待办和底部导航；再依次点击五个页签，观察标题和选中态。UI 截图只能证明截图时的可见状态，不能替代类型检查、HAP 产物和安装存在性检查。

十五、M1 手工验证记录模板

步骤	操作	预期结果	记录内容
1	执行`build.ps1`	类型检查和构建成功	构建输出摘要
2	检查 HAP	文件存在且非空	产物名称和大小
3	安装 HAP	设备存在应用包	Bundle 名称
4	启动应用	Ability 打开首页	首屏截图
5	检查首页	标题、卡片、待办、导航可见	页面观察结果
6	点击首页	首页保持高亮	导航状态
7	点击机台	机台占位页和机台高亮	页面观察结果
8	点击调机	调机占位页和调机高亮	截图
9	点击异常	异常占位页和异常高亮	页面观察结果
10	点击报表	报表占位页和报表高亮	页面观察结果

表格中的“预期结果”是检查标准，不是额外的运行结论。实际记录应填写真实执行结果，遇到失败时保留失败阶段和日志摘要，不要只记录最终的“未通过”。

十六、分层排错路径

16.1 命令找不到 Hvigor

先检查DEVECO_STUDIO_HOME是否设置，再检查tools/hvigor/bin/hvigorw.bat是否存在。不要先修改 ArkTS 页面，因为页面代码还没有进入编译阶段。

16.2 Java 或 Node 版本不一致

检查脚本是否设置了JAVA_HOME、NODE_HOME和Path前缀。如果 IDE 中可以构建、终端脚本失败，优先比较两次构建使用的工具路径。

16.3 HAP 构建成功但应用无法启动

先确认 HAP 是否安装成功，再检查 Bundle 名称和EntryAbility。如果 Ability 已启动但页面空白，再查看loadContent('pages/Index')的路径和错误日志。

16.4 页面能启动但导航不正确

这属于 UI 状态链路问题，应回到 D-004 和 D-006 的配置、Store、@State、@Link和ForEachkey 检查，不要重新安装 SDK。

十七、发布前限制与下一阶段

M1 当前没有正式签名，不进行发布包验证；只检查一个手机模拟器尺寸，没有覆盖平板和 2in1；首页仍使用脱敏演示数据；机台、调机、异常和报表的完整业务流程尚未全部实现。因此可以发布“从零搭建 M1 并完成限定范围验证”的技术文章，但不能把它写成完整 App 已上线或 API 24 全面兼容认证。

下一篇 D-008 将从 M1 的运行验证进入 M2 机台档案，首先建立MachineStatus、Machine和DemoMachineRepository，为后续机台列表、筛选和详情功能准备数据基础。

十八、常见问题

1. 为什么 DevEco Studio 里能运行，还要保留 build.ps1？

脚本能把工具路径、模块、产品和构建命令固定下来，便于命令行复现和排错。多人协作时，脚本也比“按照某个人的 IDE 点击顺序操作”更容易检查。

2. unsigned HAP 能不能直接发布？

不能把调试阶段的 unsigned HAP 当作正式发布包。它可以用于当前模拟器验证，但正式上架、真机分发和持续交付需要配置正确签名。

3. API 24 模拟器运行后，可以写成“API 24 已兼容”吗？

不建议。应该写明编译 SDK、运行设备和验证范围，例如“API 26 Beta SDK 构建的 M1 包，在 API 24 模拟器完成安装、启动和五项导航检查”。完整兼容性还需要覆盖更多设备形态和业务流程。

4. 为什么 M1 只验证占位页？

M1 的目标是验证工程骨架、首页和导航链路。把未完成模块明确显示为占位态，比把静态页面包装成已完成业务更诚实，也便于后续按里程碑扩展。

十九、把构建、安装和运行分成三种证据

初学者经常把“构建成功”“安装成功”和“页面运行正确”当成同一件事。实际上它们发生在不同阶段，验证对象也不同：构建成功说明源码和工程配置通过了编译流程；安装成功说明设备接受了 HAP；运行正确还需要观察应用启动、页面渲染和交互链路。三种结果必须分别记录，才能在出现问题时快速定位。

证据类型	证明了什么	不能证明什么
Hvigor 构建日志	代码能够按当前工程配置生成产物	设备一定能安装
HAP 文件存在	构建流程生成了包文件	页面逻辑一定正确
`hdc install`成功	设备接受了安装包	首屏和导航一定无误
启动后截图	指定设备上出现了某个画面	所有设备形态都兼容
交互记录	指定用例在当前环境表现正常	未覆盖的业务流程没有问题

文章中把证据分开写，不是增加仪式感，而是避免错误结论。例如 HAP 文件存在但启动闪退，排查重点应该转向签名、运行时依赖或设备环境；如果应用能启动但点击导航无反应，构建工具链通常不是第一怀疑对象。

二十、构建前先固定环境信息

构建脚本中的路径变量不是越多越好，而是为了把本机工具链差异明确写出来。DevEco Studio、Java、Node、HarmonyOS SDK 和 Hvigor 可能来自不同目录，如果直接依赖当前终端的环境变量，一台电脑成功并不代表另一台电脑能复现。脚本开始处检查路径存在性，可以把“命令找不到”提前变成明确错误。

建议在验证记录中保存以下非敏感信息：DevEco Studio 大版本、当前工程的 API 配置、编译使用的 SDK 版本、模拟器 API 版本、Java 和 Node 的主版本、构建命令及产物名称。不要记录账号、密钥、设备认证信息和个人目录；这些内容不属于文章复现条件，也不应上传到公开博客。

1. 编译 SDK 与运行 API 必须分开写

本项目当前记录的边界是：使用 API 26 Beta SDK 完成构建，在 API 24 模拟器进行安装、启动和交互观察。这个表述说明了构建工具链和运行环境分别是什么，不能简写成“使用 API 24 SDK 编译”或“已经证明 API 24 全面兼容”。读者可以据此复现同一范围的观察，也能知道哪些结论仍然需要更多设备验证。