as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持
原生
Skip to main content
Vega设备运行Vega设备操作系统 (OS)。您的应用需声明其支持的一个或多个操作系统版本,以确保能够在用户设备上正确安装和运行。本指南阐述了操作系统版本的兼容性模型、模型管理命令,以及如何保护新版操作系统中引用的库API。 如果您正在为Vega构建全新的React Native应用,请完整阅读本页内容。如果应用运行正常,且需要添加 [os.version] 部分,则可以从升级现有应用入手。如果应用支持多个OS版本,请参阅使用isPresentOnOS保护新API,了解如何安全地使用新API。 要查找特定OS版本提供的API,请参阅Vega API引用。要查找支持的第三方库版本,请参阅支持的库和服务。

操作系统版本与SDK版本的对比

操作系统版本和SDK版本是两个不同的概念,如下表所述。 下文将介绍OS版本。

版本兼容性矩阵

下表显示了React Native运行时和每个Vega SDK版本对应的设备OS版本,以及您可以在其上构建的主机。
  • 在OS版本中引入是每个SDK版本附带的设备OS版本。目前,所有Vega设备都会收到每次OS更新,因此现场设备运行最新的可用OS。(将来可能会有所改变。)
  • 支持的主机是您可以在上面构建Vega应用的开发计算机。Windows不是支持的构建主机。对Intel Mac的支持将于2026年12月15日结束。

OS版本和React Native运行时

每个操作系统版本包含一个或多个React Native运行时,而您的应用就运行在其中一个运行时上。无需显式设置运行时。Vega CLI会自动从package.json中的@amazon-devices/react-native-*依赖项版本中读取,项目当前依赖的版本即决定了所用的运行时。 CLI会在输出中显示其解析的运行时,例如📦 Installed packages for OS Version 2.0 + RN 0.72。要预览不同的运行时间,请将--rn-version传递给vega project install,但通常的路径是让CLI读取package.json。 OS 1.2提供两种React Native运行时,如下表所述。 OS 1.2引入RN 0.83后,基于0.83运行时构建的应用无法将min设为低于1.2的版本。在此之前的OS版本均未搭载0.83运行时。当min低于运行时所需的OS版本时,vega project doctor和构建流程就会报错,提示您使用更高版本的min。两者均不会自动修改该值。 由于应用针对单个运行时构建,且始终运行于其上,因此无需对React Native运行时进行运行时保护。构建工具会保持这种一致性,不会让您依赖无法兼容项目运行时的@amazon-devices/*程序包版本。通过isPresentOnOS提供的运行时保护适用于在min之后的OS版本中添加的库API,不适用于运行时差异。

[os.version] 清单部分

要声明您的应用支持的OS版本范围,请在manifest.toml中添加一个 [os.version] 部分。
  • min - 应用支持的OS最旧版本。应用可安装在支持该版本及更高版本的设备上,并可自由使用min中的API。
  • target - 构建应用时所用的OS最高版本。您可以调用此版本及之前版本的所有API,但必须保护min之后的版本中添加的API,使应用能在旧设备上运行。
对于SDK 2.0,将min和target都设置为2.0。有关原因以及何时应将min设置为1.2,请参阅选择最低版本。 从SDK 0.24开始,需要构建 [os.version] 部分。缺少该部分时,使用npx react-native build-vega的构建将失败。手动添加,或者让工具使用vega project update-manifest --os-min 2.0 --os-version 2.0添加。有关三种编写方式及分别所需的标记,请参阅清单 [os.version] 部分。 该工具会在应用的OS版本模块到达min时记录为needs,在到达min和target之间时记录为wants。您无需写入这些条目。每次构建时,构建都会将其生成到验证、暂存和打包清单中,而不是生成到您的源manifest.toml中。有关完整的示例清单,请参阅清单 [os.version] 部分。有关这些条目本身的更多信息,请参阅清单 [needs] 部分和清单 [wants] 。

设置应用兼容性

要设置OS版本兼容性,请通过项目根目录运行以下命令。
  1. vega project install --fix会将@amazon-devices/*依赖项与OS版本兼容的版本解析为package.json。
  2. npm install会安装已解析的版本。使用项目当前所用的程序包管理器即可。
  3. vega project doctor会在您构建之前对项目进行验证。
  4. npx react-native build-vega会构建您的应用并生成vpkg.您也可以使用package.json中定义的构建脚本。
vega project命令永远不会为您运行npm、yarn或pnpm,因此请在任何更改package.json的命令之后运行您自己的程序包管理器。 doctor会确认您的OS版本有效,且min不高于target。它同时还会检查程序包版本是否匹配,以及您的代码是否会保护新API。检查未通过则会以非零状态退出,因此适用于CI管道。有关完整选项列表,请参阅vega project doctor。 除了此设置链以外,其余vega project命令可以处理范围更小的任务。要添加单个新@amazon-devices/*程序包,请运行vega project install <package>并使用程序包管理器进行安装。要在应用之前预览对其他OS目标的更改,请运行vega project update --os-version <v> --dry-run。有关所有命令和选项,请参阅Vega SDK CLI引用。

升级现有应用

要为正在运行的应用添加OS版本兼容性,您无需重写任何内容。
  1. 手动或使用vega project update-manifest --os-min 2.0 --os-version 2.0向您的manifest.toml添加一个 [os.version] 部分。
  2. 运行vega project install --fix以将@amazon-devices/*依赖项重新对齐到OS目标。
  3. 运行npm install,然后运行vega project doctor以确认您的项目兼容。
  4. 按照正常流程构建应用。
要在一个命令中创建该部分并重新对齐依赖项,请运行vega project install --fix --os-min 2.0 --os-version 2.0。这种方法需要同时使用两个标记。没有--os-version,则无法为缺少 [os.version] 部分的项目解析目标,从而导致操作失败且无法写入任何内容。 现有代码仍能运行。如果应用支持多个操作系统版本,则只需保护您决定采用的新API。

使用isPresentOnOS保护新API

当应用支持多个OS版本时(即min版本低于target版本),旧设备可能无法显示引入新API的库版本。在此类设备上调用未经保护的API会导致崩溃。 要保护该调用,请使用isPresentOnOS,它会报告在指定版本或更高版本中,运行设备的OS中是否存在对应的库。
isPresentOnOS(libraryName, version)采用以下参数:
  • libraryName - npm库名称,例如:'@amazon-devices/react-native-gesture-handler'。
  • version - semver版本字符串,例如'2.2.0'。这是库自己的版本,不是OS版本。在指定版本及更高版本中,如果运行设备的OS存在对应的库,则函数会返回true。
isPresentOnOS来自@amazon-devices/kepler-compatibility。为避免重复检查,请将结果缓存在useMemo挂钩中,而不必在每次渲染时调用。有关兼容性库的更多信息,请参阅启用向后兼容性。 vega project doctor和Vega ESLint均会标记出未经保护使用的新API。要抑制对某个导入的检查,请在前一行中添加// @os-version-ok注释。

保护原生代码

对于kepler.projectType设置为native的项目,vega project doctor还会检查C和C++源代码中是否使用了OmniKit IDL接口。OmniKit IDL接口的唯一保护措施是对QueryInterface或TryQueryInterface结果进行运行时空值检查。围绕该查询设置的OS版本或功能条件不会抑制调查结果。
仅将QueryInterface<T>()用于在min时保证的接口。使用TryQueryInterface<T>()并在接口可能不存在时检查nullptr。 要抑制对一个原生调用的检查,请在以下位置之一添加// @os-version-ok注释。原生位置与JavaScript位置不同,后者在导入之前的行中显示。
  • 位于发出调用的行的末尾。注释仅抑制该调用。
  • 独自位于调用正上方的行上。
调用上方两行或更多行处的注释并不能抑制调查结果。注释必须仅包含指令,因此诸如// do NOT add @os-version-ok here的注释也不能将其抑制。指令区分大小写,必须完全匹配,因此@OS-VERSION-OK和@os-version-okay不起作用。

跨OS版本测试

在提交应用之前,请安装min和target OS版本的设备模拟器,然后验证应用在两个版本上均可正常安装和运行。重点关注受保护的代码路径和回退方案。

相关主题

最后修改于 2026年10月23日