一、能看到页面不等于完成验证前几篇已经完成了 M1 的首页、五项导航、数据模型和组件拆分。此时在 DevEco Studio 中看到页面只能说明某一次运行路径成功还不能回答下面几个问题ArkTS 类型检查是否通过Hvigor 是否真正生成了 HAPHAP 是否安装到了目标模拟器应用是否能启动并保留正确的导航状态API 26 Beta SDK 编译、API 24 模拟器运行和“API 24 全面兼容”是否是同一件事。这一篇把 M1 的构建脚本、安装检查、交互验证和版本口径整理成一条可复现流程。下文只报告测试实际观察到的结果不把局部运行扩大成完整兼容认证。二、先明确本次验证口径M1 测试报告中的环境信息如下项目本次实际值编译工具DevEco Studio Beta 26.0.0.461 内置 Hvigor编译 SDKHarmonyOS SDK API 26 Beta1版本 26.0.0.23运行设备HarmonyOS API 24 模拟器设备 API24应用com.atan.enotebook验证范围安装、启动、首页首屏和五项导航因此本文采用这样的准确表述M1 使用 API 26 Beta SDK 构建成功并在一个 API 24 模拟器中完成安装、启动和指定交互检查。这不等同于“使用 API 24 SDK 编译成功”也不等同于“整个 App 已经完成 API 24 全面兼容”。编译 SDK、兼容目标、运行设备和业务覆盖范围需要分别说明。三、构建脚本先固定工具链项目根目录中的build.ps1负责调用 DevEco Studio 安装目录里的 Hvigor$ErrorActionPreferenceStop$projectRootSplit-Path-Parent$MyInvocation.MyCommand.Path$devecoRoot$env:DEVECO_STUDIO_HOMEif([string]::IsNullOrWhiteSpace($devecoRoot)){throwDEVECO_STUDIO_HOME is not configured}$hvigorJoin-Path$devecoRoottools\hvigor\bin\hvigorw.bat$nodeHomeJoin-Path$devecoRoottools\node$javaHomeJoin-Path$devecoRootjbr$sdkHomeJoin-Path$devecoRootsdk1. 为什么先设置 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)){throwRequired 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:PathDevEco Studio 自带的 Java、Node 和 SDK 需要与当前 Hvigor 工具链匹配。如果机器同时安装了其他 Java 或 Node 版本直接使用系统环境变量可能出现“IDE 中能运行命令行失败”的差异。这里把 IDE 目录中的工具放到当前 PowerShell 进程的环境变量中Hvigor 子进程会继承这些值。Path把 Java 和 Node 的 bin 目录放在前面减少被系统其他版本优先命中的可能。六、在正确目录执行 assembleHapPush-Location$projectRoottry{$hvigor--mode module-p moduleentrydefault-p productdefault assembleHapif($LASTEXITCODE-ne0){throwHvigor failed with exit code$LASTEXITCODE}}finally{Pop-Location}1.Push-Location和Pop-Location构建前切换到工程根目录构建结束后无论成功还是失败都恢复调用者原来的目录。finally能保证清理动作执行减少脚本对当前终端环境的副作用。2.--mode module当前命令按模块模式执行并通过-p moduleentrydefault指定 Entry 模块和 default 变体。-p productdefault指定产品配置最后的assembleHap负责完成编译和 HAP 组装。3. 为什么检查$LASTEXITCODE外部批处理程序的失败状态通过$LASTEXITCODE返回。即使 PowerShell 没有抛出普通异常也要检查这个退出码否则 Hvigor 失败后脚本可能继续结束让调用方误以为构建成功。七、执行构建和查看产物在工程根目录执行.\build.ps1本次测试的关键结果是检查项结果ArkTS 类型检查通过输出包含TYPE CHECK SUCCESSFULHAP 构建通过输出包含BUILD SUCCESSFULHAP 产物entry-default-unsigned.hap非空应用签名尚未配置正式签名当前为 unsigned HAP构建成功后产物位于 Entry 模块的 default 输出目录。调试阶段生成 unsigned HAP 可以用于当前模拟器检查但正式上架、真机分发和持续交付仍需要配置签名。八、安装和启动不是构建的附属步骤HAP 生成后还要检查它是否真的进入目标设备并能启动。M1 测试报告确认了模拟器中存在com.atan.enotebookBundle 元数据中的compileSdkVersion为26.0.0.23设备 API 为 24EntryAbility能够启动首页首屏能显示标题、四个指标、三条待办和底部导航。这几项分别覆盖了安装存在性、构建元数据、运行设备、入口能力和首屏内容。只看到构建日志中的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 形成的布局与数据链路。切换调机页签后正文显示占位内容底部导航选中态同步变化图 2M1 调机页签的状态联动结果。人工检查结果包括首页没有横向溢出指标卡没有相互覆盖底部导航没有遮挡正文调机页签标题和选中态一致。十一、哪些结论现在不能写当前证据支持的结论是M1 ArkTS 源码通过当前编译器检查API 26 Beta SDK 构建成功并生成 HAPHAP 在一个 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 根目录不绑定某台电脑的个人安装路径。$ErrorActionPreferenceStop$projectRootSplit-Path-Parent$MyInvocation.MyCommand.Path$devecoRoot$env:DEVECO_STUDIO_HOMEif([string]::IsNullOrWhiteSpace($devecoRoot)){throwDEVECO_STUDIO_HOME is not configured}$hvigorJoin-Path$devecoRoottools\hvigor\bin\hvigorw.bat$nodeHomeJoin-Path$devecoRoottools\node$javaHomeJoin-Path$devecoRootjbr$sdkHomeJoin-Path$devecoRootsdkforeach($requiredPathin ($hvigor,$nodeHome,$javaHome,$sdkHome)){if(-not(Test-Path-LiteralPath$requiredPath)){throwRequired 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:PathPush-Location$projectRoottry{$hvigor--mode module -p moduleentrydefault -p productdefault assembleHapif($LASTEXITCODE-ne0){throwHvigor failed with exit code$LASTEXITCODE}}finally{Pop-Location}读这段脚本时不要只关注最后的assembleHap。前面的路径检查决定命令是否能找到工具环境变量决定 Hvigor 使用哪套 Java、Node 和 SDKPush-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 全面兼容”。读者可以据此复现同一范围的观察也能知道哪些结论仍然需要更多设备验证。2. 为什么要检查退出码命令行工具可能输出大量日志单纯搜索“BUILD SUCCESSFUL”并不是最稳妥的判断方式。脚本应该检查命令的退出码退出码非零时立即停止后续安装步骤。否则构建失败后仍然执行安装读者看到的可能只是“找不到旧 HAP”或“安装了上一次产物”这会让验证记录失真。二十一、本篇小结本篇完成了 M1 首个可运行版本的验证闭环用 PowerShell 脚本固定 DevEco 工具链检查 Hvigor、Java、Node 和 SDK 路径通过assembleHap生成 HAP 并检查退出码验证安装、启动、首屏和五项导航记录 API 26 Beta SDK 编译与 API 24 模拟器运行的边界至此从工程骨架、数据模型、导航状态、首页组件一路讲到构建验证。下一篇进入 M2 机台档案先用 ArkTS 建立机台状态、吨位和现场位置的数据模型。