错误场景一：要求能力集 > 支持能力集 (最致命的安装错误)

这是最直接、最严格的错误场景。它会在应用安装阶段就彻底“失败”。

• 错误本质：应用向设备声明：“我运行的最低要求是必须具备 A、B、C 三项能力”，但设备检查了一下自己的“能力清单”，发现自己只有 A 和 B，缺少 C。

• 如何人为制造这个错误：

  1. 场景设定：我们开发一个应用，目标设备是“手机 (Phone)”和“平板 (Tablet)”。通常，手机具备 NFC 能力，而大部分平板不具备。

  2. 错误操作：开发者认为应用的核心功能是“NFC 读写”，离开 NFC 就毫无价值。于是，他在模块的 syscap.json 文件中，强制将 NFC 能力添加到了“要求能力集”。

     // 在模块的 src/main/syscap.json 文件中
     {
       "devices": {
         "general": [
           "default", // 对应 Phone
           "tablet"
         ]
       },
       "development": {
         "addedSysCaps": []
       },
       "production": {
         // "production" 字段影响最终打包的 "要求能力集"
         "addedSysCaps": [
           // 开发者强行将NFC设为必须项
           "SystemCapability.Communication.NFC.Core"
         ],
         "removedSysCaps": []
       }
     }
     

• 产生的后果与表现：

  1. 在应用分发阶段（AppGallery）：

     • 当一个不带 NFC 的平板用户在应用市场上搜索这个应用时，应用市场后台会进行匹配：
       • 应用的要求能力集：{..., SystemCapability.Communication.NFC.Core}
       • 平板的支持能力集：{...} (不包含 NFC)
       • 匹配失败。
     • 结果：该用户在应用市场上根本看不到也搜不到这个应用。从用户的角度看，应用“消失”了。

  2. 在应用安装阶段（手动安装 HAP 包）：

     • 假设用户通过其他渠道获取到了这个应用的 HAP 安装包，并尝试在自己的无 NFC 平板上手动安装。
     • 设备上的包管理器 (BundleManager) 在安装时会进行同样的验证。
     • 验证失败。
     • 结果：设备会弹出一个明确的**“安装失败”**提示。失败原因通常会指向“应用与您的设备不兼容”或类似的描述。应用无法被安装到系统中。

• 总结：这个错误不会导致应用运行时崩溃，因为它从根本上阻止了应用被安装在一个不满足其最低要求的设备上。这是一种前置的、保护性的失败。开发者犯的“错”是：

  • 错误一（业务决策错误）：将一个非绝对必要的功能（或者可以有替代方案的功能）定义为了“必须要求”，导致用户群不必要地缩小。
  • 错误二（配置错误）：错误地修改了 production 配置，导致应用无法分发给预期的目标设备。

---

错误场景二：联想能力集 > 支持能力集 (最常见的运行时崩溃)

开发中最常遇到的问题，也是例子中重点讨论的场景。

• 错误本质：开发工具（DevEco Studio）为了让你能为所有目标设备开发，向你展示了所有设备能力的并集。你使用了设备 A 的专属 API，但应用最终却运行在了只具备能力 B 和 C 的设备 D 上。

• 如何人为制造这个错误：

  1. 场景设定：创建一个支持“手表 (Wearable)”和“智慧屏 (TV)”的项目。手表有振动器 (Vibrator)，而智慧屏没有。

  2. 默认配置：默认情况下，syscap.json 的development（联想能力集）部分是手表和智慧屏能力的并集，所以 SystemCapability.Sensors.Vibrator.Core 是包含在内的。这导致你在写代码时，可以顺利地联想出振动相关的 API。

  3. 错误操作：开发者编写了一个通用弹窗组件，希望在弹窗出现时给用户一个振动反馈，但他忘记了智慧屏没有振动器。

     // 错误代码：想当然地认为所有设备都有振动器
     import vibrator from '@ohos.vibrator';
     import dialog from '@ohos.promptAction';
     
     @Entry
     @Component
     struct Index {
       showDialog() {
         // 直接调用振动 API，未做任何判断
         try {
           vibrator.startVibration({
             type: 'preset',
             effectId: 'haptic.clock.timer'
           }, {
             usage: 'notification'
           });
         } catch (e) {
           // 简单的日志，但应用逻辑继续
           console.error("Vibration failed: " + JSON.stringify(e));
         }
     
         dialog.showDialog({
           title: '提示',
           message: '这是一个跨设备弹窗'
         });
       }
     
       build() {
         Button('显示弹窗').onClick(() => this.showDialog())
       }
     }
     

• 产生的后果与表现：

  1. 在手表上运行：

     • 手表支持 SystemCapability.Sensors.Vibrator.Core。
     • vibrator 模块被成功导入。
     • 调用 startVibration 成功，手表产生振动。
     • 一切正常。

  2. 在智慧屏上运行：

     • 智慧屏不支持 SystemCapability.Sensors.Vibrator.Core。
     • 根据系统版本和 API 实现，可能会发生以下两种情况之一：
       • 情况A (模块导入为 undefined)：import vibrator from '@ohos.vibrator' 语句执行后，vibrator 变量为 undefined。当代码执行到 vibrator.startVibration(...) 时，相当于 undefined.startVibration(...)，会立即抛出 TypeError: Cannot read properties of undefined。如果没有顶层 try-catch 捕获这个致命错误，应用会直接崩溃闪退。
       • 情况B (API 调用返回 801 错误)：模块导入成功，但调用 startVibration 时，底层服务不存在，API 内部直接抛出 BusinessError，错误码为 801 (能力不支持)。在上面的代码中，这个错误会被 catch 住并打印日志，应用不会崩溃，但振动功能静默失败。

• 总结：这是最典型的运行时兼容性错误。应用可以成功安装，但在特定设备上执行到特定代码路径时，由于调用了不存在的系统能力而导致功能异常或程序崩溃。

总结表格

为了让你更清晰地理解，这里有一个对比表格：

错误场景	能力集关系	错误如何产生	错误发生阶段	错误表现
安装失败	要求能力集 > 支持能力集	开发者在 syscap.json 中错误地将非必要能力加入 production.addedSysCaps	应用分发与安装	应用市场不可见；手动安装时提示不兼容/安装失败。
运行时崩溃	联想能力集 > 支持能力集	开发者直接调用了某设备专属的 API，且未用 canIUse 或 try-catch 做运行时保护	应用运行	功能静默失败、BusinessError(如801)、TypeError、应用崩溃闪退。

这两个场景有着容易混淆的地方！

当代码在智慧屏上试图调用振动API时，那一刻代码的“要求”确实大于了智慧屏的“支持”。这为什么不能归结于要求>支持？

在HarmonyOS的开发体系中，“要求能力集 (Required Capability Set)”是一个有特定技术定义的、静态的概念，它和你代码在运行时那一刻的“动态要求”是两回事。

我们必须把这两个“要求”区分开：

1. 静态的、安装时的“要求能力集” (The App’s “Passport”)
2. 动态的、运行时的“代码要求” (The Feature’s “Ticket”)

下面我用一个比喻来彻底讲清楚。

---

比喻：出国旅游

把你的应用想象成一个旅行团，把不同设备想象成不同的国家。

• 支持能力集 = 一个国家的旅游资源（比如，瑞士有雪山，马尔代夫有沙滩）。
• 要求能力集 = 办理这个国家签证所需的最低材料（比如，必须有护照、有存款证明）。
• 联想能力集 = 你手里拿着一本**《全球旅游完全指南》**，里面介绍了滑雪、潜水等所有可能的项目。
• API调用 = 实际去参加一个具体的旅游项目（比如，去滑雪场滑雪）。

场景一：要求能力集 > 支持能力集 (签证被拒)

你组织了一个“必须滑雪”主题的旅行团。你在旅行团的**招生简章（要求能力集）**上白纸黑字地写着：“本团成员必须前往滑雪场，因此只招收能提供滑雪服务的国家”。

• 你的操作：在 syscap.json 的 production 部分，加入了 "SystemCapability.Skiing.Core"（一个虚构的“滑雪”能力）。
• 后果：
  • 当旅行团试图进入**瑞士（支持滑雪）**时，海关（包管理器）一看，简章要求和国家资源匹配，允许入境（安装成功）。
  • 当旅行团试图进入**马尔代夫（不支持滑雪）**时，海关一看，简章要求滑雪，但本国没有雪山，直接拒绝入境（安装失败）。

在这个场景里，错误发生在进入国家（安装应用）之前。你的“要求能力集”是一个硬性的、前置的门槛。

---

场景二：联想能力集 > 支持能力集 (到了地方发现景点没开)

你组织了一个“瑞士马尔代夫两国深度游”的旅行团。为了让行程看起来丰富，你的**旅游指南（联想能力集）**里既包括了滑雪，也包括了潜水。

但是，你的**签证要求（要求能力集）**非常宽松，只写了“有护照就行”，没有强制要求必须能滑雪或必须能潜水。这样，你的旅行团可以顺利地进入瑞士，也可以顺利地进入马尔代夫。

• 你的操作：在代码里写了这样一个行程：function goToSkiResort() { ... }。你参考了旅游指南，知道有这个项目，但没有提前打电话问景点是否开放。

• 后果：

  • 在瑞士（支持滑雪）：旅行团到了瑞士，你带着大家去调用 goToSkiResort()，滑雪场正常开放，大家玩得很开心（代码运行正常）。
  • 在马尔代夫（不支持滑雪）：旅行团到了马尔代夫，你也带着大家去调用 goToSkiResort()。结果到了地方发现，这里只有沙滩，根本没有滑雪场！此时，你的旅行团就“当场崩溃”了（应用运行时崩溃）。

在这个场景里，应用已经成功安装（旅行团已经入境）。错误发生在你试图执行一个设备不支持的功能时。

核心区别

对比维度	场景一 (安装失败)	场景二 (运行时崩溃)
官方术语	要求能力集 > 支持能力集	代码的动态要求 > 支持能力集
“要求”的性质	静态的、声明式的，在syscap.json中定义	动态的、执行式的，在.ets代码中通过API调用体现
检查者	AppGallery、包管理器 (PackageManager)	操作系统运行时 (Runtime)
检查时机	应用分发和安装时	应用运行时，执行到具体代码行时
失败后果	无法安装，应用根本进不了系统	应用崩溃或功能异常
如何产生的	开发者错误地配置了 syscap.json，提高了安装门槛	开发者未对可选功能做运行时判断 (canIUse)

从最底层的逻辑看，两个场景都是因为设备能力不足。但从HarmonyOS的工程化和应用生命周期管理角度看，它们是发生在完全不同阶段、由不同机制处理、导致不同后果的两种截然不同的错误。

• 要求能力集，是用来管理应用的可安装性 (Installability)。
• 运行时检查 (canIUse)，是用来管理应用内功能的可访问性 (Accessibility)。