维度

内容

本章主题

真机交付如何把构建、签名、安装和验收串成一条线

核心文件

build-profile.json5、entry/src/main/module.json5、AppScope/app.json5、hvigorw.bat

读者目标

看懂工具链对齐、签名安装和缓存清理的真实排查顺序

输出结果

一套可复用的真机交付检查表

先看结论真机交付不是最后点一次安装按钮，而是先把版本、签名、权限和缓存全部对齐，再让应用在真实设备上稳定启动。只要这条链路通了，前九章的功能才算真正落地。

# 先构建完整交付物
.\hvigorw.bat assembleApp

# 查看打包产物
Get-ChildItem .\entry\build\default\outputs\default

# 安装到真机
hdc install -r .\path\to\app-release.app

步骤

命令或输入

输出或关注点

构建

.\hvigorw.bat assembleApp

生成完整交付包，而不是只看页面能否预览

安装前检查

hdc list targets

确认设备在线、可安装、状态正常

安装

hdc install -r .\path\to\app-release.app

完整包写入真机

验收

启动应用并查看首页、拍照、录音、统计

确认功能链路真的闭环

{
  "app": {
    "products": [
      {
        "name": "default",
        "targetSdkVersion": "6.1.0(23)",
        "compatibleSdkVersion": "6.0.2(22)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ]
  }
}

检查项

当前项目状态

说明

目标 SDK

6.1.0(23)

真机交付以这个目标为准

兼容 SDK

6.0.2(22)

保留旧设备兼容边界

严格模式

已开启

路径、资源和引用更容易提前暴露问题

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "requestPermissions": [
      "ohos.permission.CAMERA",
      "ohos.permission.MICROPHONE",
      "ohos.permission.APPROXIMATELY_LOCATION",
      "ohos.permission.LOCATION"
    ]
  }
}

{
  "signingConfigs": [
    {
      "name": "release",
      "type": "HarmonyOS",
      "material": {
        "storeFile": "<p12>",
        "storePassword": "<password>",
        "keyAlias": "<alias>",
        "keyPassword": "<password>",
        "profile": "<p7b>",
        "certpath": "<cer>"
      }
    }
  ]
}

配置项

当前值

对交付的作用

mainElement

EntryAbility

真机启动入口

deliveryWithInstall

true

安装时连同应用一起交付

installationFree

false

保持正常安装流程

权限集合

CAMERA / MICROPHONE / LOCATION

支撑拍照、录音和定位水印

# 真机安装排查顺序
hdc list targets
hdc install -r .\path\to\app-release.app
hdc shell hilog | findstr /i "EntryAbility"

# 如果需要重装，先卸载旧包
hdc uninstall com.example.project027

症状

更可能的原因

先查什么

device is unauthorized

设备未授权或证书不匹配

设备连接状态和签名 profile

verify app signature failed

证书或 profile 与安装包不一致

build-profile 和真机授权

install failed

旧包残留或安装缓存异常

产物目录和 hdc 输出

功能能开但不完整

只打了 entry，HSP 没一起进包

是否执行完整 assembleApp

# 关闭 IDE 后再清理缓存
Remove-Item -LiteralPath 'D:\HvigorUserHome\project_caches' -Recurse -Force
Remove-Item -LiteralPath 'D:\HvigorUserHome\caches' -Recurse -Force

# 重新构建
.\hvigorw.bat assembleApp

缓存现象

处理方式

备注

EPERM unlink

清理 project_caches 后重试

多半是文件占用或旧缓存残留

产物不更新

删旧输出再重新构建

避免拿到旧包误判

构建反复失败

关闭 IDE 后再清缓存

先释放文件锁

验收项

通过标准

对应页面

首页启动

能正常进入主界面

首页

权限弹窗

相机、麦克风、定位按需弹出

拍照页、录音页

拍照保存

能生成记录并回到列表

拍照页、记录页

录音保存

能录、能停、能回放

录音页、记录页

统计刷新

周/月/年切换后结果变化

统计页

本章收官第十章把留痕从工程、签名、安装一路走到真机验证。到这里，前面九章的页面、服务层、存储和统计才真正进入可以交付的状态。