Vega SDK发布说明

请在此处为您的Vega SDK使用体验评分（仅提供英文版）。

Vega SDK 0.24版本

Vega SDK 0.24版本为Vega引入了更现代化的React Native 0.83版本，提供了更好的兼容性、更高的性能以及更优的开发者体验。此外，0.24版本支持通过CLI进行开发者模式身份验证，对WebView主版本进行了升级，并引入了全新的无障碍功能设置Turbo模块。

此版本要求在Vega Fire TV Stick上安装OS 1.2 (2101020054720)，其与Vega SDK v0.24.x兼容。您可以导航到My Fire TV（我的Fire TV）>关于来查看设备软件版本。

公告

现已推出适用于Vega的React Native 0.83

此版本包含适用于Vega的React Native 0.83抢先体验版，以便应用开发者和库开发者着手将现有的React Native 0.72项目迁移到更现代化的React Native版本中，其支持大量针对Vega平台构建的现有React Native社区库，并提供相关文档及更新后的参考应用程序。对于入门的Vega开发者而言，此版本提供了基于React Native 0.83更新的全新应用模板。

React Native 0.83提供一系列新功能，包括React 19及配套的React编译器（消除手动记忆化）、Hermes v1（运行时性能提升，启动更快）、Yoga 3.x（CSS对齐布局），以及替代Flipper的新React Native DevTools，Metro bundler启动速度提升约15倍，且新增了boxShadow和filter等样式属性。此版本还启用了密度无关像素 (DIP)，确保用户界面尺寸在不同屏幕密度下保持一致。同时默认启用并发呈现器 (Fabric)，在复杂的用户界面过渡期间实现更流畅的交互。

React Native 0.72仍受支持，您可以自行安排迁移时间。

有关与RN 0.83兼容的React Native社区库清单，请参阅支持的库和服务。

需要采取行动： 着手规划迁移到0.83版本的相关工作。现有的RN 0.72应用仍照常运行。准备就绪后，请参阅下方的迁移指南、AI辅助升级工具和更新后的示例应用，开始进行迁移。

请参阅适用于Vega的React Native参考

应用清单中规定的操作系统版本

Vega SDK 0.24要求您在应用清单中声明操作系统的目标版本和最低版本。此版本仅支持Vega OS 1.2，因此请将两个版本均设置为1.2。

要添加多个版本，请执行以下命令，然后重新构建应用：

vega project update-manifest --os-min 1.2 --os-version 1.2

在此命令中，--os-min用于确定应用正常运行所需的最低操作系统版本。亚马逊应用商店拒绝将应用提交到或安装到Vega OS版本低于此值的平台上。--os-version用于指定首选的Vega OS目标版本，即已通过兼容性测试的应用版本。在后续的Vega OS版本迭代中，部分系统行为会有所调整。此目标版本可向系统提供提示，以判断是否启用回退行为来保持与您应用的兼容性。

该命令会添加 [os.version] 配置段和必要模块条目，然后报告更改内容：

📋 操作系统版本：min=1.2, target=1.2
   OS-version模块： 1个必需模块（最低版本），0个可选模块（最高到目标版本）

✅ 已使用 [os.version] 配置块和1个必需模块，完成manifest.toml更新。您的@amazon-devices/*程序包条目会在构建时重新生成。

您也可以手动添加该部分到manifest.toml中。将操作系统添加到 [[needs.module]] 配置段中，并在新的 [os.version] 配置段中分别添加目标版本和最低版本，如下例所示。

[[needs.module]]
id = "/com.amazon.vega.os@IVega_1_2"

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

缺失该配置段会导致构建失败，并显示类似于以下内容的错误消息：

缺失 [os.version].target。Vega应用程序必须声明其操作系统版本。添加到manifest.toml：[os.version] target = "<版本>" min = "<版本>"或执行：vega project update-manifest --os-version <版本> --os-min <版本>
缺失 [os.version].min。声明 [os.version] 中的最低版本和目标版本。
发生不可恢复错误，Vega操作失败：vega build拒绝执行： manifest.toml中存在2处OS-version合规性错误 。请参阅上文。

需要采取行动： 添加 [os.version] 配置段，并将min和target均设置为1.2。

对Intel Mac (x86_64)的支持即将到期

SDK 0.24是最后一个支持Intel Mac (x86_64)的版本，该服务将于2026年12月15日到期。您需要在到期前完成Apple Silicon Mac或Ubuntu x86_64的迁移工作，确保持续获得SDK更新、安全补丁和经过测试的构建版本。此要求同样适用于在Intel macOS运行器上运行的CI/CD管道。

逐步弃用实验性API

Vega SDK公开了将在Open Beta过渡工作中逐步弃用的实验性API。在0.24 SDK版本中，这些实验性API仍然可用，但已纳入弃用流程，将在后续版本中彻底移除。

需要采取行动： 如果您的应用使用了实验性API，建议在后续SDK版本中规划迁移。

新功能

通过CLI进行开发者模式身份验证

您现在可以直接通过CLI在Vega设备上启用开发者模式，无需手动在开发者门户中添加许可名单。执行vega devmode login命令，利用开发者凭证进行身份验证。设备会自动关联至您的组织，您可以随时切换组织。

请参阅启用开发者模式

通过虚拟设备捕获已呈现的用户界面

Vega虚拟设备现已支持将文本复制粘贴到设备中，并转储已呈现的用户界面内容。您可以捕获屏幕内容的纯文本形式，也可以获取完整的视图层级结构树，将其保存到主机文件中。这项改进使虚拟设备在功能上更贴近其他模拟器的开发者工具标准，有助于更轻松地调试布局和焦点问题。

请参阅在Vega虚拟设备上运行应用

虚拟设备上的家长监护集成

虚拟设备现已支持家长监护 (PCON) 集成，无需依赖实体设备，即可在本地开发和测试过程中模拟家长监护行为。

请参阅在Vega虚拟设备上运行应用

无障碍功能设置TurboModule

新增的@amazon-devices无障碍功能设置TurboModule (KeplerA11ySettingsInterfaceTurbo)，使React Native应用能以编程方式访问隐藏字幕样式及其他系统无障碍功能设置。采用此设置的应用能在运行时，查询隐藏字幕的字体、颜色和背景样式，以匹配用户的系统无障碍功能偏好。不依赖无障碍功能设置的应用不受影响。所有应用均可读取设置。设置无障碍功能值的操作受运行时权限的限制。

请参阅Vega A11y设置

改进

GitHub上的React Native 0.83参考应用

公共参考应用已针对React Native 0.83进行更新，并已发布到开源示例代码库的专用分支中。这些参考应用不仅演示了RN 0.83工具链的使用方式，还为正在评估升级的团队提供了有效的迁移示例。

请参阅示例应用

适用于React Native 0.83的WebView 4.0.0

v0.24中的WebView基于Chromium 144，现已同时支持两种React Native轨道： 适用于RN 0.72的WebView 3.5.7和适用于RN 0.83的WebView 4.0.0及更高版本（目前最新版本为4.0.2）。WebView 4.0.x具备网页功能（JavaScript警报对话框、Web Audio API），且默认启用明文HTTP安全策略。后续版本将弃用适用于RN 0.72的WebView，建议您尽快将应用迁移至RN 0.83。将依赖项更新到"@amazon-devices/webview": "~4.0.2"，然后执行npm install。

请参阅Vega网页应用

已解决的问题

Apple-Silicon Mac回归问题：虚拟设备、真机启动及IDE设备检测

Apple-Silicon（M系列）Mac上出现的一系列阻碍性问题均指向同一个根本原因：设备适配器中的一项更改将压缩库的链接方式改为动态链接，但开发者机器上并无对应的动态库，导致适配器二进制文件在启动时崩溃。由于大量工具均依赖于设备适配器，该崩溃问题同时引发了三种异常表现：虚拟设备未能在启动时限内完成启动、应用无法部署到已连接的设备，且已连接的设备会从IDE的设备列表中消失。恢复静态链接即可修复上述三个问题。

调试版本中的视频播放功能已恢复

在调试构建版本中，媒体应用程序会在加载时卡顿，或在视频画面空白的情况下仅播放音频。原因在于React Native更改了RN 0.72到RN 0.83之间的事件名称规范化方式：原生媒体表面事件无法传递到JavaScript呈现器，始终未能创建视频表面。媒体库现在会同时以两种命名规范派发每个事件，无需您更改任何代码，即可恢复调试构建版本以及旧版应用包应用中的播放功能。

修复WebView播放和呈现问题 (WebView 4.0.x)

WebView 4.0.x解决了RN 0.83轨道上的一系列媒体和呈现问题：

• 修复了部分直播中视频画面无法适配播放窗口的问题。
• 修复了受保护媒体播放过程中的播放中断问题。
• 修复了滚动浏览内容后，视频画面压缩变形或尺寸显示错误的问题。
• 修复了连续播放多个广告后音视频卡顿的问题。
• 修复了因无效用户代理导致Service Worker注册失败的问题。
• 修复了蓝牙音频设备切换时屏幕黑屏的问题。

vega exec tool –version现已重新支持报告工具版本

v0.22版本引入了一项回归缺陷，导致vega exec <tool> --version打印的是CLI/SDK版本，而非底层工具版本。现在，除非第一个参数是已知的CLI命令，否则CLI会将版本和帮助标记转发给目标工具，从而恢复了预期行为。如果您此前编写了应对脚本，则可以在v0.24版本中将其简化回vega exec <tool> --version。

vega device copy-logs支持裸工件名称

当工件名称未附带提供者后缀时，vega device copy-logs --artifact <name>会因不可恢复错误而失败，原因在于SDK将工件索引替换为了undefined。现在会对输入进行验证，通过则正常解析，失败则返回可操作的错误信息。文档中记载的工件/提供者长格式保持不变，仍可正常使用。

已知问题

React Native 0.83不支持Chrome DevTools

当目标版本是React Native 0.83时，不支持Chrome DevTools (CDT) 调试功能。如果您正在预览RN 0.83，请使用React Native DevTools（随附于RN 0.83）进行调试，而非CDT。对于已升级为RN 0.83的应用而言，这属于预期行为，不会影响RN 0.72项目。

Cookie管理器未初始化，导致相关操作失败。

在当前版本中，由于原生Cookie管理器 (ICookieManager) 未初始化，导致设置、获取和清除等操作失败，并发生未找到Cookie管理器的错误。该问题导致Cookie库中的部分API无法正常使用。应用的关键启动流程不受影响。我们计划在后续版本中提供完整支持。

React Navigation中的轻微视觉问题

核心导航功能运行正常 — 屏幕过渡、堆栈路由及选项卡路由均可正常工作。仍存在部分轻微的视觉问题：

• 从子示例返回后，屏幕上出现黑色条纹或叠加层。
• 打开后，抽屉和Material顶部选项卡内容会向左偏移。
• 部分堆栈导航器屏幕中的文本无法完全显示。

我们计划在后续版本中提供完整的视觉支持。

React Native 0.83中的无头任务崩溃

在React Native 0.83目标版本中，对于在自身 [[processes.group]] 中执行 [[components.task]] 或 [[components.service]] 命令的应用，启动时会崩溃，并出现ReferenceError: Property '__DEV_RUNTIME__'不存在的错误。受影响的无头任务（如消息接收器、EPG同步和安装任务）会静默失败，导致后台消息无法送达、数据无法同步。交互式应用功能不受影响。我们计划在后续版本中进行修复。

临时解决方法是将"useSystemJsBundlesForHeadlessJs": false添加到应用package.json文件的kepler配置段中，将无头捆绑包构建为独立包：

"kepler": {
  "projectType": "application",
  "appName": "YourAppName",
  "targets": ["tv"],
  "useSystemJsBundlesForHeadlessJs": false
}

此配置会将所有polyfill直接打包到无头任务或服务中。交互式应用包仍沿用系统包，因此其大小和启动时间保持不变。无头捆绑包会增大100–300KB，启动速度略慢。此解决方法需要KeplerCLIPlatform 0.22.14或更高版本。修复版本发布后移除此标记。

重要须知： 此解决方法旨在解除RN 0.83迁移和开发工作中的阻碍性问题。此配置会禁用无头任务的系统包优化功能，请勿将使用功能配置的应用提交到亚马逊应用商店。面向生产环境的应用应在官方发布修复版本后，先移除该临时解决方法再发布。

expo-image在自动链接时崩溃

使用某些expo-image TurboModule功能时，expo-image库可能会在运行时崩溃，并报错Failed auto-linking libexpo-image-2.so: 无法打开共享对象文件： 此类文件或目录不存在。根本原因在于自动链接配置中的库名错误。我们计划在后续版本中进行修复。

React Native 0.83不支持setNativeProps

在React Native 0.83上调用setNativeProps()的应用会崩溃，并报错TypeError: undefined不是函数。setNativeProps为Fabric呈现器不支持的旧版API，这与上游React Native在iOS和Android上的表现一致。

需要采取行动： 使用声明式状态驱动属性替换setNativeProps()调用。例如，使用React state更新组件样式，而不是通过命令式方式更新。此操作遵循了React Native的官方迁移指南。

Expo库尚未稳定

以下Expo库已包含在Vega OS中，但尚未针对RN 0.83完成稳定化或迁移工作。在面向v0.24 SDK构建的应用中，这些库将无法正常运行。依赖这些库的开发者应继续使用RN 0.72，直至后续版本完成稳定化适配，或考虑下方列出的替代方案。

• @amazon-devices/expo-font — 目前暂无替代方案
• @amazon-devices/expo-gl — 目前暂无替代方案
• @amazon-devices/expo-image-manipulator — 目前暂无替代方案
• @amazon-devices/expo-notifications — 目前暂无替代方案
• @amazon-devices/expo-splash-screen — 使用Vega SplashScreenManager API
• @amazon-devices/expo-sqlite — 暂无直接替代方案；稳定化工作已在计划中
• @amazon-devices/expo-system-ui — 使用根View的背景颜色样式

Last updated: 2026年8月6日