前言

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、设备系统版本和项目配置都要一起记录，否则很容易把不同环境下的结果混在一起。

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

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

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

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

我们可以用一个 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 时，版本字段、依赖包和构建配置都要单独检查。

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

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

第一个坑，是把 API 不可见 直接记成 API 不存在。更准确的写法应该是：已发布、文档可查、SDK 可见、Beta 可测、项目可用中的哪一个状态。

第二个坑，是看到编译通过以后，马上判断迁移完成。编译通过只能说明工程构建完成，还要继续跑安装、启动、权限、主流程、旧数据和日志。

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

如果使用 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、权限、设备和项目主流程。

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

这里有几个坑要单独记。

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 或设备版本可能消失；今天暂未验证的能力，下一轮文档和工具链可能已经具备测试条件。每个问题都要有状态、优先级和下一步，不然问题越记越多，项目会很难推进。

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

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

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

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

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 实测问题，要单独记下来。

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

我们可以按照五类处理。

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

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