Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases

Console

as

新手入门
设计和开发
应用发布
参考
支持

操作系统目标版本

操作系统目标版本

Vega设备运行Vega设备操作系统 (OS)。您的应用需声明其支持的一个或多个操作系统版本，以确保能够在用户设备上正确安装和运行。本指南阐述了操作系统版本的兼容性模型、模型管理命令，以及如何保护新版操作系统中引用的库API。

如果您正在为Vega构建全新的React Native应用，请完整阅读本页内容。如果应用运行正常，且需要添加[os.version]部分，则可以从升级现有应用入手。如果应用支持多个操作系统版本，请参阅使用isPresentOnOS保护新API，了解如何安全地使用新API。

要查找特定操作系统版本提供的API，请参阅Vega API引用。要查找支持的第三方库版本，请参阅支持的库和服务。

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

操作系统版本和SDK版本是两个不同的概念，如下表所述。

  操作系统版本 SDK版本
定义 应用运行时所用的设备操作系统版本，如1.2。 应用构建时所用的Vega SDK工具链版本。
位置 位于manifest.toml中的 [os.version] 部分。 位于vega-sdk-requirements.json文件。有关详细信息，请参阅管理SDK版本。
目标 应用必须支持的已发布设备。 本地构建环境。

下文将介绍操作系统版本。

操作系统版本和React Native运行时

每个操作系统版本包含一个或多个React Native运行时，而您的应用就运行在其中一个运行时上。无需显式设置运行时。Vega CLI会自动从package.json中的@amazon-devices/react-native-*依赖项版本中读取，项目当前依赖的版本即决定了所用的运行时。

CLI会在输出中显示其解析的运行时，例如📦 已安装的程序包，适用于操作系统版本1.2 + RN 0.72。要预览不同运行时，请将--rn-version传递到vega project install，但常规方法是让CLI读取package.json。

操作系统1.2提供两种React Native运行时，如下表所述。

React Native运行时 可用版本 说明
RN 0.72 操作系统1.2 既定运行时。
RN 0.83 操作系统1.2 操作系统1.2中引入的较新运行时。

操作系统1.2引入RN 0.83后，基于0.83运行时构建的应用无法将min设为低于1.2的版本。在此之前的操作系统版本均未搭载0.83运行时。当min低于运行时所需的操作系统版本时，vega project doctor和构建流程就会报错，提示您使用更高版本的min。两者均不会自动修改该值。

由于应用针对单个运行时构建，且始终运行于其上，因此无需对React Native运行时进行运行时保护。构建工具会保持这种一致性，不会让您依赖无法兼容项目运行时的@amazon-devices/*程序包版本。通过isPresentOnOS提供的运行时保护适用于在min之后的操作系统版本中添加的库API，不适用于运行时差异。

[os.version] 清单部分

要声明应用支持的操作系统版本范围，请在manifest.toml中添加 [os.version] 部分。

已复制到剪贴板。

[os.version]
target = "1.2"
min = "1.2"

  • min - 应用支持的操作系统最旧版本。应用可安装在支持该版本及更高版本的设备上，并可自由使用min中的API。

  • target - 应用构建时所用的操作系统最新版本。您可以调用此版本及之前版本的所有API，但必须保护min之后的版本中添加的API，使应用能在旧设备上运行。

自SDK 0.24起，构建时必须含有 [os.version] 部分。缺少该部分会导致npx react-native build-vega构建失败。您可以手动添加，也可以由工具通过vega project update-manifest --os-min 1.2 --os-version 1.2自行添加。有关三种编写方式及分别所需的标记，请参阅清单 [os.version] 部分。

当min提供应用的操作系统模块，工具会在清单中将其记录为needs；当这些模块在min之后、target之前的版本中引入，则将其记录为wants。您无需写入这些条目。每次构建时会自动生成。有关完整的示例清单，请参阅清单 [os.version] 部分。有关条目本身的更多信息，请参阅清单 [needs] 部分和清单 [wants] 部分。

设置应用兼容性

要设置操作系统版本兼容性，请通过项目根目录运行以下命令。

已复制到剪贴板。

vega project install --fix
npm install
vega project doctor
npx react-native build-vega

  1. vega project install --fix会解析@amazon-devices/*依赖项中与操作系统版本兼容的版本，并写入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会确认您的操作系统版本有效，且min不高于target。同时还会检查程序包版本是否匹配、min中是否存在可用的所需模块，以及您的代码是否会保护添加的API。检查未通过则会以非零状态退出，因此适用于CI管道。有关完整选项列表，请参阅vega project doctor。

除此设置链以外，其余vega project命令可以处理范围更小的任务。要新增一个@amazon-devices/*程序包，请运行vega project install <程序包>，并使用程序包管理器进行安装。要在应用前先预览对不同操作系统目标作出的更改，请运行vega project update --os-version <v> --dry-run。有关所有命令和选项，请参阅Vega SDK CLI引用。

升级现有应用

要为正在运行的应用添加操作系统版本兼容性，您无需重写任何内容。

  1. 使用手动方式或使用vega project update-manifest --os-min 1.2 --os-version 1.2，为您的manifest.toml添加 [os.version] 部分。

  2. 运行vega project install --fix，将您的@amazon-devices/*依赖项重新对齐到操作系统目标。

  3. 依次运行npm install和vega project doctor，确认您的项目具备兼容性。

  4. 按照正常流程构建应用。

要在命令中创建该部分并重新对齐依赖项，请运行vega project install --fix --os-min 1.2 --os-version 1.2。这种方法需要同时使用两个标记。如无--os-version，则无法为缺少 [os.version] 部分的项目解析目标，从而导致操作失败且无法写入任何内容。

现有代码仍能运行。如果应用支持多个操作系统版本，则只需保护您决定采用的新API。

使用isPresentOnOS保护新API

当应用支持多个操作系统版本时（即min版本低于target版本），旧设备可能无法显示引入新API的库版本。在此类设备上调用未经保护的API会导致崩溃。

要保护该调用行为，请使用isPresentOnOS，它会报告在指定版本或更高版本下，运行设备的操作系统中是否存在对应的库。

已复制到剪贴板。

import { isPresentOnOS } from '@amazon-devices/kepler-compatibility';
import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

// @amazon-devices/react-native-gesture-handler 2.2.0提供此功能。
// 仅在设备已安装该版本的情况下使用。
function DraggableItem() {
  if (isPresentOnOS('@amazon-devices/react-native-gesture-handler', '2.2.0')) {
    return <GestureHandler.NewFeature />;   // 新路径
  }
  return <GestureHandler.LegacyFeature />;  // 旧设备回退
}

isPresentOnOS(libraryName, version)采用以下参数：

  • libraryName - npm库名，例如'@amazon-devices/react-native-gesture-handler'。

  • version - semver版本字符串，例如'2.2.0'。在指定版本及更高版本下，如果运行设备的操作系统存在对应的库，则函数会返回true。

isPresentOnOS来自@amazon-devices/kepler-compatibility。为避免重复检查，请将结果缓存在useMemo挂钩中，而不必在每次渲染时调用。有关兼容性库的更多信息，请参阅启用向后兼容性。

vega project doctor和Vega ESLint均会标记出未经保护调用的新API。要跳过某项import检查，请在前一行中添加// @os-version-ok注释。

已复制到剪贴板。

// @os-version-ok
import { openCamera } from '@amazon-devices/kepler-camera';

跨操作系统版本测试

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

Last updated: 2026年8月21日

关注我们:
amazon_developer_logo

© 2010-2026 年，亚马逊公司或其附属公司. 保留所有权利。

协议

开发人员博客

联系我们