【HarmonyOS 7开发者前瞻】12 HarmonyOS 7 API 26 验证问题记录指南：环境、日志与回归清单

前言

API 26 Beta 阶段做实测，最怕的不是遇到问题，而是问题没有被记录清楚。

同样一个现象，可能来自不同原因。比如项目编译失败，可能是 SDK 配置问题，也可能是依赖版本问题，还可能是某个新 API 暂时没有进入当前 SDK。应用安装失败，可能和签名有关，也可能和设备版本、包名、构建产物有关。页面运行异常，可能是 API 26 行为变化，也可能是原来项目里的状态管理问题在新环境里被暴露出来。

HarmonyOS 7 API 26 Developer Beta1 面向开发调测，开发者可以体验 API 26.0.0 Beta1 的新能力和新特性，并使用 DevEco Studio 进行应用开发；这个阶段也提供邀请测试和远程真机云调试等验证方式。Beta 阶段适合持续记录、对照验证和问题反馈，单次测试结果不要直接写成长期结论。

所以，API 26 实测问题记录要有一个基本原则：

每个坑都要绑定环境、现象、复现路径、日志和当前结论。

今天我们整理了一套适合 HarmonyOS 7 API 26 Beta 的实测问题记录方式。你后面验证新 API、迁移 HarmonyOS 6 项目、接 Skill、接 Agent、验证 AI 能力、多端适配、使用 DevEco Code 或 DevEco CLI，都可以按这套方式把问题单独记下来。

一、先把问题和环境绑在一起

实测问题记录的第一步，是把环境写清楚。

很多问题单之所以后面没法复查，不是因为现象描述太少，而是没有记录环境。比如 编译失败 这四个字没有太大价值，必须继续补充 DevEco Studio 版本、HarmonyOS SDK 版本、API 版本、项目分支、设备版本、构建命令、错误日志。

API 26 开始，版本号采用 X.Y.Z 语义化版本格式；SDK 版本、Release Type、设备系统版本和项目配置都要一起记录，否则很容易把不同环境下的结果混在一起。

可以先给每个问题单固定这些字段。

字段	记录内容	为什么要记
验证日期	具体日期	方便对照 Beta 更新
DevEco Studio	完整版本号	判断工具链差异
HarmonyOS SDK	SDK 版本和 Release Type	判断 API 环境
项目分支	当前验证分支	方便回滚和对照
设备环境	本地真机、远程真机、模拟器	区分运行环境
系统版本	设备系统版本	判断设备侧差异
项目状态	新建项目或存量项目	区分基线项目和业务项目
复现次数	偶现或稳定复现	判断问题优先级

这里有一个很容易踩的坑：远程真机结果和本地真机结果不要混写。

HarmonyOS 7 新能力页提到，可以通过 AGC 远程真机云调试服务筛选 API 26 或系统版本为 7.0.0.23 的设备，上传软件包后进行远程调试。这个能力很适合补齐设备条件，但它和本地真机的交互、权限弹窗、日志采集、性能感受并不完全一样。

建议问题单里单独区分环境。

环境	适合记录什么
本地真机	安装、权限、交互、日志、性能体感
远程真机	API 26 设备覆盖、基础页面运行、兼容性现象
模拟器	页面布局、低风险逻辑、快速回归
新建项目	排除历史依赖和业务代码影响
存量项目	验证真实迁移成本和主流程问题

我们可以用一个 JSON 模板统一记录。

{
  "issueId": "API26-001",
  "date": "2026-06-xx",
  "devecoStudio": "填写 DevEco Studio 版本",
  "sdkVersion": "填写 HarmonyOS SDK 版本",
  "apiVersion": "API 26",
  "releaseType": "Beta1",
  "projectBranch": "feature/harmonyos7-api26",
  "projectType": "new-project | existing-project",
  "deviceType": "local-device | remote-device | emulator",
  "deviceModel": "填写设备型号",
  "systemVersion": "填写系统版本",
  "reproducible": "stable | occasional | once"
}

二、编译构建类问题要单独记录

API 26 实测里，编译构建问题最容易先出现。

这类问题一定要单独记，不要和运行时问题混在一起。因为编译问题还没有进入设备侧，它通常和 SDK、工程配置、依赖版本、类型检查、API 可见性、资源配置、构建插件有关。

HarmonyOS 工程里的 compatibleSdkVersion、targetSdkVersion、compileSdkVersion 需要满足 compatibleSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion，配置不符合规则会报错。迁移到 API 26 时，版本字段、依赖包和构建配置都要单独检查。

编译构建类问题可以按下面几类记录。

问题类型	典型现象	先查什么
SDK 配置问题	SDK 找不到、版本不匹配	DevEco Studio、SDK 安装、API 版本
版本字段问题	compile、target、compatible 报错	三个 SDK 版本关系
依赖冲突	HAR、ohpm 包构建失败	依赖版本和兼容范围
API 不可见	import 失败、符号不存在	文档、API Reference、本地 SDK
类型检查问题	ArkTS 类型报错	类型定义、空值、泛型、接口变化
资源构建问题	图片、配置、路径异常	资源命名、目录、配置文件
构建插件问题	hvigor 或构建任务失败	插件版本、构建脚本、缓存

这里有两个坑要单独标出来。

第一个坑，是把 API 不可见 直接记成 API 不存在 。

更准确的写法应该是：已发布、文档可查、SDK 可见、Beta 可测、项目可用中的哪一个状态。

第二个坑，是看到编译通过以后，马上判断迁移完成。

编译通过只能说明工程构建完成，还要继续跑安装、启动、权限、主流程、旧数据和日志。

我们可以准备一个如下的构建问题记录表。

字段	内容
错误编号	API26-BUILD-001
错误类型	SDK 配置 / 依赖冲突 / API 不可见 / 类型错误
出现阶段	clean / build / preview / package
文件位置	具体文件或配置项
错误信息	保留完整错误文本
初步判断	当前怀疑原因
修改范围	单文件 / 配置项 / 依赖版本
复测结果	编译通过 / 仍失败 / 暂缓

如果使用 DevEco Code 或其他 AI 工具解释构建错误，也要把工具建议和最终结果分开。DevEco Code 面向鸿蒙应用开发，覆盖需求、设计、开发、验证四个阶段；但工具建议本身只是排查线索，真正结论要回到重新编译和运行结果。

可以这样记录工具辅助排查。

{
  "issueId": "API26-BUILD-001",
  "type": "compile-error",
  "file": "填写文件路径",
  "errorMessage": "粘贴关键错误信息",
  "toolSuggestion": "填写 DevEco Code 或其他工具建议",
  "changeScope": "single-file | config-only | dependency-change",
  "buildResult": "passed | failed | pending",
  "conclusion": "adopted | rejected | need-more-check"
}

三、安装运行类问题要记录完整链路

编译通过以后，下一类坑会出现在安装和运行阶段。

这一类问题也要单独记。因为它已经从构建环境进入设备环境，问题来源可能变成签名、包名、设备版本、权限授权、入口页、路由参数、数据库读取、状态刷新、旧数据兼容。

建议大家每次 API 26 实测都跑一条最小运行链路。

安装应用 → 启动应用 → 首页加载 → 列表读取 → 详情跳转 → 新建保存 → 返回刷新 → 日志确认

对于会议类项目，可以这样记录。

链路节点	常见问题	需要保存什么
安装应用	安装失败、签名异常、包名冲突	安装提示、构建产物、设备版本
启动应用	白屏、闪退、入口异常	崩溃日志、启动截图
首页加载	首屏空白、加载慢、状态异常	首屏截图、关键日志
列表读取	历史数据缺失、数据库异常	数据样本、错误日志
详情跳转	路由参数丢失、页面打不开	路由参数、跳转日志
新建保存	表单保存失败、数据不刷新	输入样本、保存结果
返回刷新	列表未更新、状态错乱	页面录屏或截图
日志确认	无日志、日志过滤错误	日志命令、过滤条件

这里有一个非常常见的坑：只测新建数据，不测旧数据。

存量 HarmonyOS 6 项目迁移到 API 26 时，旧数据很重要。历史会议、录音路径、联系人、待办、项目关联、用户设置，这些都要重新打开。新建数据正常，只能说明新流程能写入，不能说明旧数据能兼容。

旧数据可以单独记一张表。

数据类型	要验证什么
历史会议	标题、时间、标签、参会人是否可读
录音路径	文件路径是否有效，权限是否正常
纪要内容	文本是否正常显示和编辑
待办事项	状态、责任人、截止时间是否正常
联系人	关联关系是否丢失
项目数据	项目和会议是否仍然关联
用户设置	通知、外观、同步配置是否保留

权限也要分开记录。权限问题经常表现得像功能问题，比如按钮点击没有反应、数据不显示、保存失败。API 26 实测时，至少要把 授权同意 和 授权拒绝 两条路径都走一遍。

权限场景	同意后	拒绝后
录音	是否可录音	是否提示回退
文件	是否可读取保存	是否提供替代路径
通知	是否可提醒	是否提示开启方式
联系人	是否可选择联系人	是否允许手动输入
相册	是否可选择图片	是否保留页面状态

运行类问题记录要比编译问题更细。因为运行问题往往涉及用户路径，一句 详情页打不开 不够。更好的记录方式是写清楚从哪个页面进入、带了什么参数、设备状态是什么、日志是什么、是否稳定复现。

四、新能力和 AI / Agent 问题要记录状态

API 26 实测中，最容易引发争议的是新能力问题。

比如 Skill、Agent、视觉 AI、空间化、多窗交互、安全、性能相关能力，可能已经出现在新能力页面里，但项目里暂时还没有跑通。这个时候，问题记录要写成状态，不能写成一句 不可用。

HarmonyOS 7 新能力页围绕智能化、空间化、多窗交互、安全、性能等方向展示新能力，Skill、Agent 和视觉 AI 都在智能化方向中出现。对项目来说，看到能力名称只是第一步，后面还要继续确认文档、SDK、权限、设备和项目主流程。

我们可以继续使用这张状态表。

状态	判断依据	记录方式
已发布	新能力页、HDC 信息、活动页出现	记录能力名称和方向
文档可查	Guide、版本说明、API Reference 能查到	记录文档入口和接入条件
SDK 可见	本地 SDK 或 DevEco Studio 能识别	记录 import 和构建结果
Beta 可测	本地真机或远程真机能运行	记录设备、日志和截图
项目可用	真实项目主流程跑通	记录项目场景和回归结果
暂未验证	缺少文档、SDK、设备或权限	记录阻塞条件和下一步

这里有几个坑要单独记。

坑	更稳的记录方式
发布会上看到能力，本地 SDK 找不到	已发布，SDK 暂未验证
文档能查到，项目 import 失败	文档可查，本地 SDK 或工程配置待检查
import 成功，运行失败	SDK 可见，设备、权限或服务条件待确认
远程真机成功，本地真机失败	环境差异，需要分开记录
Demo 成功，项目失败	Demo 可测，项目主流程待适配
AI 输出不稳定	记录输入样本、输出结果和确认状态
Agent 链路中断	记录中断节点、失败原因和回退路径

AI / Agent 类问题还要特别注意确认边界。生成纪要草稿、提取待办草稿、生成周报草稿，可以先作为候选结果；自动发送、自动删除、自动分配责任人、修改关键数据，要单独记录为高风险动作，不能混进普通成功路径。

可以给 AI / Agent 问题单增加这些字段。

{
  "issueId": "API26-AI-001",
  "ability": "meeting-summary | action-extract | agent-workflow",
  "sourceStatus": "published | doc-visible | sdk-visible | beta-testable | project-available | pending",
  "inputSample": "填写输入摘要",
  "outputSample": "填写输出摘要",
  "needUserConfirm": true,
  "failureNode": "input | ability-call | output-parse | user-confirm | save-result",
  "fallback": "retry | manual-edit | cancel | keep-draft",
  "currentConclusion": "继续验证 | 暂缓接入 | 可进入最小链路"
}

这个模板可以避免一个问题：只记录 AI 能力 好用 或 不好用。真正有价值的是输入是什么、输出是什么、失败在哪个节点、是否需要用户确认、是否有回退。

对于会议类应用，建议先把最小链路单独记下来。

会议文本 → 纪要草稿 → 待办草稿 → 用户确认 → 保存草稿

这条链路跑通之前，不建议继续记录 自动发送周报 、自动分配责任人 、自动删除无效记录 这类高风险问题。先把低风险链路测稳定，再扩展高风险动作。

五、最后把问题单变成回归清单

问题记录不能只停留在发现问题。最后要变成回归清单。

因为 Beta 阶段会持续更新。今天出现的问题，下一轮 SDK 或设备版本可能消失；今天暂未验证的能力，下一轮文档和工具链可能已经具备测试条件。每个问题都要有状态、优先级和下一步，不然问题越记越多，项目会很难推进。

可以先把问题优先级分成三类。

优先级	问题类型	处理建议
P0	无法编译、无法安装、无法启动、主流程崩溃	立即处理
P1	核心功能异常、权限异常、旧数据异常、新能力最小链路失败	优先处理
P2	低频页面异常、视觉细节、体验优化、复杂 Agent 链路	排期处理
P3	文档待查、暂未验证、观察项	记录并等待更新

每个问题还要有处理状态。

状态	含义
open	已发现，尚未处理
investigating	正在排查
blocked	被设备、SDK、文档、权限或服务条件阻塞
fixed	已修复
verified	已复测通过
postponed	当前阶段暂缓
closed	已关闭并有结论

最终我们可以形成一张 API 26 实测问题总表。

问题编号	分类	优先级	环境	现象	当前状态	下一步
API26-BUILD-001	编译构建	P0	DevEco + SDK	构建失败	investigating	保存完整日志
API26-RUN-001	安装运行	P0	本地真机	启动白屏	open	查看启动日志
API26-PERM-001	权限	P1	本地真机	拒绝权限后无回退	open	补充拒绝路径
API26-DATA-001	旧数据	P1	存量项目	历史会议读取异常	investigating	准备旧数据样本
API26-API-001	新能力	P2	SDK	新 API 未找到	blocked	查文档和 SDK
API26-AI-001	AI 链路	P1	最小样例	待办提取不稳定	open	增加输入样本
API26-TOOL-001	工具链	P2	DevEco Code	修复建议未通过编译	open	记录建议和结果

回归时，可以按照这个顺序处理。

P0 编译安装启动 → P1 主流程权限旧数据 → P1 最小 AI 链路 → P2 新能力和体验问题 → P3 观察项

这里还有最后一个坑：修复后不做回归。

问题修复只是第一步。修复后至少要重新跑当前链路，并确认有没有影响其他主流程。比如修复会议详情页状态刷新问题以后，要继续检查会议列表、详情跳转、新建保存、返回刷新。这样才算问题进入 verified 状态。

可以准备一个回归记录模板。

{
  "issueId": "API26-RUN-001",
  "fixVersion": "填写修复分支或提交",
  "retestEnvironment": "local-device | remote-device | emulator",
  "retestResult": "passed | failed",
  "affectedFlows": [
    "app-start",
    "meeting-list",
    "meeting-detail",
    "create-meeting",
    "return-refresh"
  ],
  "finalStatus": "verified | reopened | postponed"
}

这套记录会让 API 26 实测不再是零散截图和聊天记录，而是一套可以持续维护的问题库。后续 Beta 更新时，只要回到这张表里筛选 P0、P1 和 blocked 项，就知道下一轮该优先验证什么。

总结

HarmonyOS 7 API 26 实测问题，要单独记下来。

这里的 单独记，不是随手写一句现象，而是把问题拆成环境、分类、复现、日志、状态和下一步。

我们可以按照五类处理。

类别	要单独记什么
环境信息	DevEco Studio、SDK、API 版本、设备、项目分支
编译构建	SDK、版本字段、依赖、API 可见性、类型和资源问题
安装运行	签名、启动、页面链路、权限、旧数据和日志
新能力 / AI / Agent	能力状态、输入输出、确认边界和失败节点
回归清单	优先级、处理状态、复测结果和关闭结论

对于会议类项目，第一轮实测可以先关注这些坑：

坑	记录重点
API 26 环境没记录	版本和设备必须写清楚
新建项目没跑就迁移存量项目	先建立干净基线
API 找不到直接写不可用	先放进能力状态表
编译通过就认为迁移完成	继续跑安装、启动和主流程
远程真机和本地真机混写	两种结果分开记录
权限只测同意不测拒绝	拒绝路径也要保存
只测新数据不测旧数据	历史数据样本必须验证
AI / Agent 直接执行高风险动作	先做草稿和确认链路
工具建议没有验证结果	建议必须绑定编译和运行结果
修复后不做回归	fixed 之后还要 verified

Beta 阶段的问题会持续变化。只要问题单记录清楚，后续 SDK、文档、设备和工具链更新以后，就可以继续回到同一张表里复查。这样做，HarmonyOS 7 API 26 实测就不会变成一堆零散现象，而会沉淀成真正可复用的项目适配经验。