纹渊 HarmonyOS 7 工程实战（18）：签名包安装后的模拟器验收清单

一、安装成功只是验收起点

签名包能够安装，只能证明包格式、签名材料和目标设备在当前条件下兼容。真正的交付验收还要回答：桌面图标能否启动正确 Ability，首帧资源是否完整，页面切换是否保留状态，权限拒绝后能否继续使用，以及重新安装或覆盖安装后数据是否符合预期。

把这些检查临时记在脑中，很容易漏掉“能启动但首屏白屏”“手机正常而平板布局溢出”“权限弹窗取消后按钮永久加载”等问题。更稳妥的方法是把一次模拟器验收建模为有阶段、有证据、有失败原因的记录。

二、先核对包身份与设备范围

安装前应确认应用身份、版本和设备声明彼此一致。版本号决定覆盖安装顺序，包名决定启动和数据隔离，设备类型决定模拟器是否属于支持范围。目标 SDK 与兼容 SDK 则影响 API 能力和运行下限。

配置核对不需要把证书口令或机器路径写进记录。验收关注可公开复核的身份值、签名是否有效、包是否由预期产品生成，而不是暴露签名材料。

三、用状态机记录安装到首帧

一次完整验收可以拆成包检查、安装、启动、首帧和业务冒烟五个阶段。每个阶段只有通过后才进入下一步，失败时保留错误类型和观察到的现象。

export enum AcceptanceStage { PACKAGE_READY = 'package_ready', INSTALLED = 'installed', LAUNCHED = 'launched', FIRST_FRAME = 'first_frame', SMOKE_PASSED = 'smoke_passed' } export interface AcceptanceRecord { stage: AcceptanceStage bundleName: string versionName: string deviceType: 'phone' | 'tablet' | '2in1' startedAt: number finishedAt: number screenshotTaken: boolean failures: string[] } export function advance( record: AcceptanceRecord, next: AcceptanceStage ): AcceptanceRecord { return { ...record, stage: next, finishedAt: Date.now() } }

状态机的价值是阻止“跳验收”。如果首帧还没确认，就不能因为安装接口返回成功而填写业务冒烟通过。记录也能区分环境问题、签名问题和应用问题。

四、安装与启动必须验证同一个应用身份

安装前后的身份应形成闭环：待测包声明的 Bundle 名称、设备上查询到的应用、启动时进入的 Ability 必须一致。只按桌面图标文字判断并不可靠，因为旧版本和新版本可能使用相同名称。

interface InstalledApp { bundleName: string versionCode: number versionName: string enabled: boolean } function verifyInstalled( expectedBundle: string, expectedVersion: number, actual: InstalledApp | undefined ): string[] { const issues: string[] = [] if (actual === undefined) issues.push('设备未返回目标应用') if (actual?.bundleName !== expectedBundle) issues.push('应用身份不一致') if (actual !== undefined && actual.versionCode !== expectedVersion) { issues.push('设备版本不是本次待测版本') } if (actual !== undefined && !actual.enabled) issues.push('应用处于禁用状态') return issues }

启动后还要观察进程是否保持、页面是否进入预期入口。如果启动瞬间退出，应先记录崩溃时间和系统错误，再判断是资源、权限、API 兼容还是初始化异常，不能用反复重装掩盖问题。

五、首帧验收要检查资源、主题和安全区

纹渊首页的首帧包含标题字体、背景纹理、分类入口、轮播区和底部导航。任何一项缺失都可能说明资源未打包、字体加载失败或断点状态未初始化。首帧检查应使用结构化探针，而不是只凭“看起来差不多”。

export interface FirstFrameProbe { titleVisible: boolean backgroundVisible: boolean categoryCount: number bottomTabCount: number contentWidth: number viewportWidth: number } export function verifyFirstFrame(probe: FirstFrameProbe): string[] { const issues: string[] = [] if (!probe.titleVisible) issues.push('标题未显示') if (!probe.backgroundVisible) issues.push('背景资源未显示') if (probe.categoryCount === 0) issues.push('分类数据为空') if (probe.bottomTabCount !== 4) issues.push('底部导航数量异常') if (probe.contentWidth > probe.viewportWidth) issues.push('首帧横向溢出') return issues }

同一包至少在一个手机和一个宽屏模拟器上检查。手机关注安全区、输入框和底部导航，平板关注最大内容宽度、网格列数与双栏重排。

六、核心业务冒烟覆盖一条完整闭环

业务冒烟不需要穷举全部功能，但必须走通一条能改变状态并产生结果的路径。纹渊可以选择“搜索纹样—选中纹样—选择载体—生成预览—进入导出面板”，同时穿过搜索、状态模型、渲染组件和文件服务边界。

type SmokeStep = { name: string passed: boolean evidence: string } function smokePassed(steps: SmokeStep[]): boolean { const required = [ '搜索结果更新', '纹样选中', '载体确认', '预览生成', '导出面板可用' ] return required.every((name: string) => { const step = steps.find((item: SmokeStep) => item.name === name) return step !== undefined && step.passed && step.evidence.length > 0 }) }

证据可以是页面可见文本、状态变化或截图编号。不要只记录“点击成功”，因为按钮响应不代表后续状态和结果正确。

七、权限拒绝、覆盖安装和冷启动都要测

网络、分布式数据同步等权限具有不同触发时机。首次拒绝后，应用应保持基础浏览和创作能力，并在用户再次主动启用相关功能时给出清晰说明。覆盖安装还要核对收藏、历史和主题偏好是否保留；清除数据后的冷启动则应回到稳定默认值。

export interface RecoveryCase { name: string action: 'deny_permission' | 'upgrade_install' | 'clear_data' expected: string observed: string } export function evaluateRecovery(item: RecoveryCase): boolean { if (item.action === 'deny_permission') { return item.observed.includes('基础功能可用') } if (item.action === 'upgrade_install') { return item.observed.includes('偏好保留') } return item.observed.includes('恢复默认状态') }

八、失败要按层定位并留下可复核证据

模拟器验收最怕把所有问题归为“安装失败”。签名不匹配、版本降级、启动崩溃、首帧资源缺失和业务按钮失效属于不同层级，需要不同证据。

HarmonyOS 构建配置与产品、模块、签名之间的关系可参考构建配置文件说明。验收记录只保存必要证据，不复制签名密码、证书内容或个人目录。

九、总结

签名包验收应形成“身份核对—安装—启动—首帧—核心闭环—恢复场景”的连续证据。状态机阻止跳过阶段，结构化探针让首帧和业务结果可比较，分层故障表帮助快速判断责任边界。完成这些检查后，模拟器上的“能安装”才真正升级为可复核、可回归的交付结果。