as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持
原生
Skip to main content

为您的Vega SDK的使用体验评分

Vega SDK和OS版本2.0

Vega SDK 2.0、Vega OS 2.0和Vega开发者工具现已正式发布,不再处于公开测试阶段。Vega OS 2.0已在所有支持Vega的Fire TV设备上推出,因此您现在可以针对OS 2.0进行构建。 通过Vega 2.0,您能够:
  • 使用React Native 0.83构建更快、响应更快的应用。 React Native 0.83现已正式发布,并带来了React 19、React Compiler和Hermes v1。React Compiler在构建时处理记忆化,因此您无需再手动添加React.memo或useCallback。使用React Native DevTools调试性能问题。使用新的CSS属性(如boxShadow和outline)设置焦点状态样式。从SDK 0.24开始,有更多的库支持RN 0.83,其中包括React Navigation、Reanimated、Lottie,以及其他的Expo库。
  • 为您的React Native应用添加原生功能。 使用Vega原生API以C++构建自定义用户界面组件,并安排在应用关闭后运行的后台任务。在React Native中构建应用的其余部分。原生工具处于公开测试阶段。
  • 借助AI进行迁移和构建。 Amazon Devices Builder Tools (ADBT) for AI是使用AI编码代理进行Vega开发的推荐方式。可使用该工具来规划从RN 0.72升级到RN 0.83、将Fire OS应用迁移到React Native for Vega,以及调试性能问题。
  • 在构建之前发现兼容性问题。vega project doctor现在包括适用于JavaScript、TypeScript和原生代码的兼容性检查器。它们会标记并非在您的应用所针对的每个操作系统版本上都可用的API。
此版本要求在您的Vega Fire TV上安装OS 2.0,该操作系统与Vega SDK 2.0.x兼容。内部版本号因设备而异。请参阅操作系统内部版本。

公告

Vega的总体可用性和API稳定性

从2.0开始,Vega API接口面在次要SDK版本中保持稳定。重大更改仅在主要版本中发布,每年一次。次要版本按常规节奏发布。您可以采用每个次要版本而无需返工,并根据自己的时间安排来规划重大升级。

操作系统版本范围支持

您的应用清单现在可以声明一系列支持的操作系统版本,从最低版本到目标版本。大多数Vega设备会更新到最新的操作系统版本,因此对于大多数应用,请将min和target都设置为2.0。在未来的版本中,某些设备可能不会收到最新的操作系统版本。如果您的应用需要访问这些设备,请将min设置为您支持的最早的操作系统版本,并使用兼容性检查器来防护较新的API。 需要采取的行动: 将manifest.toml的[os.version]设置为您的应用支持的范围,然后重建。 请参阅操作系统目标版本

TextInput的Done和Back行为将与标准React Native相符

在即将发布的Vega OS版本中,React Native 0.83版本中没有submitBehavior的的单行TextInput将使用React Native默认值:blurAndSubmit。按下Done(完成)将触发onSubmitEditing,然后字段将模糊处理并关闭键盘。按下Back(返回)将在submitAction设置为'previous'时触发onSubmitEditing,然后进行相同的操作。现在,该字段在按下Done(完成)后会保持对焦,在按下Back(返回)时,会在不通知您的应用的情况下关闭键盘。用于设置submitBehavior="submit"的字段、多行字段以及React Native 0.72应用不受影响。 需要采取的行动: 如果您的RN 0.83应用将每次onSubmitEditing事件视为一次提交,请在submitAction上进行筛选,并将'previous'视为拒绝。要在按下Done(完成)后保持键盘处于打开状态,请设置submitBehavior="submit"。有关详细信息,请参阅处理密码输入事件。

重大更改

现在会在构建时生成操作系统内部版本模块条目

在SDK 0.24中,vega project update-manifest会将/com.amazon.vega.os@IVega_*条目写入源代码manifest.toml的[[needs.module]]和[[wants.module]]部分。从SDK 2.0开始,内部版本拥有这些条目,并将其从[os.version]生成到打包的清单中。vega project update-manifest现在仅写入min和target值,并且在每次运行时,它都会从源代码清单中移除工具拥有的模块条目。您为其他系统模块声明的模块条目会被保留。 在使用SDK 0.24创建的项目上,第一次运行会从源代码控制的清单中删除以下行:
需要采取的行动: 提交生成的差异,不要手动恢复已移除的条目。 请参阅清单 [os.version] 部分

深度导入不再在React Native 0.83库中解析

从SDK 2.0开始,React Native for Vega核心程序包以及Gesture Handler、Lottie、React Navigation、Reanimated、React Native SVG和React Native Screens的Vega版本仅在node_modules中公开其公共JavaScript接口。公共API保持不变。如果您的RN 0.83应用使用顶层导入,则不受影响。如果该应用它使用深入库的内部实现路径的深度导入,则您的构建将失败,因为这些路径无法解析。此更改不影响RN 0.72应用。 需要采取的行动: 如果您的RN 0.83应用使用深度导入,请将其替换为顶层导入(首选)或惰性导入。如果您的任何Jest测试依赖于库的内部实现,请改为在测试代码中模拟这些模块。

React Linear Gradient在React Native 0.83中取代为内置样式属性

React Native 0.83通过experimental_backgroundImage样式属性原生支持线性渐变,该样式属性在任何View上都接受标准CSS linear-gradient()语法。@amazon-devices/react-linear-gradient库不再需要,也不包含在RN 0.83库集中。RN 0.72应用不受影响。
需要采取的行动: 在迁移到RN 0.83时,请移除@amazon-devices/react-linear-gradient依赖项并在View上将<LinearGradient>组件取代为experimental_backgroundImage样式属性。 请参阅将LinearGradient取代为backgroundImage样式属性

在React Native 0.83中使用@shopify/flash-list而不是@amazon-devices/shopify__flash-list

在React Native 0.72上,Vega提供了自己的FlashList实现作为@amazon-devices/shopify__flash-list。在React Native 0.83上,请改用公共FlashList程序包:@shopify/flash-list。@amazon-devices/shopify__flash-list程序包不适用于React Native 0.83应用,因此仍然导入该程序包的应用在运行时会失败。RN 0.72应用不受影响。 需要采取的行动: 在迁移到RN 0.83时,请将@amazon-devices/shopify__flash-list依赖项取代为@shopify/flash-list,然后更新您的导入。

实验性API不再受支持

SDK 0.24宣布,Vega SDK的实验性API已被弃用。从SDK 2.0开始,实验性API不再受支持。 需要采取的行动: 如果您的应用使用实验性API,请在使用SDK 2.0进行构建之前迁移到支持的API。要在您的应用中查找实验性API并规划迁移,请使用Amazon Devices Builder Tools (ADBT) for AI版本1.0.19或更高版本。

新功能

使用C++构建原生用户界面组件和后台任务

React Native for Vega应用现在可以包含使用C++编写的视图和模块,并像使用任何其他组件或模块一样从JavaScript中使用它们。React Native 0.83的两个示例应用展示了操作过程。两者都在Fire TV Stick和Vega虚拟设备上运行:
  • 原生用户界面组件示例: 在React树内部渲染使用Vega用户界面工具包构建的C++视图。该示例将属性从JavaScript传递到原生代码,并将事件发送回JavaScript。它还涵盖了方向键对焦、动画、图像预取和VoiceView无障碍功能。
  • 定期后台任务示例: 将Vega任务管理器封装在C++ Turbo模块中,这样您的应用就可以重复运行无头JavaScript任务。应用关闭后,时间表将保持不变。最小间隔为60秒,每次运行最多可能需要五分钟。
任务管理器还没有JavaScript API。要安排任务,请将示例的PeriodicTasks Turbo模块复制到您的应用中。 在使用Vega原生API增强您的React Native应用博客文章中阅读更多内容。

在Vega Studio中编辑时查找并修复无障碍功能问题

Vega Studio中的A11y Inspector会在您编辑时检查您的.tsx和.jsx文件。它会标记辅助技术(例如VoiceView)无法描述或操作的组件,并提出快速修复建议。检查器使用与Vega ESLint插件相同的规则,因此其结果与您的构建管道相符。在Vega Studio 0.24.2及更高版本中,它默认处于启用状态。 请参阅在Vega Studio中查找和修复无障碍功能问题

对JavaScript和TypeScript的兼容性检查

当min小于target时,min之后引入的API可能不存在于您的应用支持的每台设备上。vega project doctor现在会对照SDK兼容性清单检查您的源代码,并报告三条规则:
  • no-unguarded-os-api(错误): 在没有防护的情况下使用min之后引入了API。
  • no-removed-api(错误): 在min仍在使用中时或之前移除了API。
  • warn-deprecated-api(警告): 在target仍在使用中时或之前弃用了API。
要修复未加防护的API,请从@amazon-devices/kepler-compatibility中将其封装在isPresentOnOS()检查中并提供回退,或提出min。isPresentOnOS()的第二个参数是提供API的库版本,而不是操作系统版本。vega project doctor在检查失败时以非零状态退出,因此您可以将其用作CI管道中的门禁。
请参阅操作系统目标版本

对原生代码的兼容性检查

对于kepler.projectType设置为native的项目,vega project doctor还会检查C和C++源代码。它会对min之后添加的OmniKit接口以及min之前移除的接口或由target弃用的接口报告未加防护的QueryInterface调用。要使用可选的较新接口,请调用TryQueryInterface<T>()并检查是否有nullptr。请仅将QueryInterface<T>()用于在min时保证的接口。 请参阅升级应用的操作系统版本兼容性

通过命令行验证账户登录集成

新kcp-cli-v2工具预装在Vega设备上,无需单独的测试工具即可检查应用的内容启动器帐户登录状态。在应用的组件shell中,运行kcp-cli-v2 account-login read-status以读取当前的登录状态。运行kcp-cli-v2 account-login watch-status以在您登录和退出应用时实时监控登录状态的变化。该工具需要开发者模式和侧载应用,不能在Vega虚拟设备上运行。 请参阅测试内容启动器集成

改进

React Native SVG中的完全文本路径支持

@amazon-devices/react-native-svg现在完全支持TextPath元素,因此您可以沿曲线或任意路径渲染文本,例如用于圆形标签和弯曲标题,而无需将文本预先渲染为图像。 请参阅react-native-svg

跨MSE分段边界的音频更加流畅

W3C媒体管道现在实现了媒体源扩展音频拼接算法并处理重叠的音频帧。在此更改之前,如果自适应流追加了重叠或填充的音频片段(例如在广告插入点或周期边界处),可能会产生可听见的咔嗒声、间隙或漂移。已解码 (PCM) 的音频现在会在到达音频接收器之前进行修剪和线性化,因此无需对应用进行任何更改即可跨分段边界连续播放。 请参阅适用于Vega的React Native 中的W3C媒体API

已解决的问题

W3C媒体能力检查中的AC-3和E-AC-3编解码器字符串

navigator.mediaCapabilities.decodingInfo()不再拒绝使用ac3、eac3或ec3编解码器字符串的配置。在此修复之前,这些字符串会被路由到AV1编解码器解析器,因此调用会失败,Shaka播放器等播放器会过滤掉所有包含AC-3音频的变体。另外,包含组合编解码器字符串的MPEG-TS SourceBuffer(例如video/mp2t; codecs="avc1.4D401F,ac3")以前会播放视频但静默地丢弃AC-3音轨。现在,这些流使用支持MPEG-TS中的AC-3的解复用器,因此可以播放音频。

dash-rel-v5.0.0-r1.8中的dash.js稳定性修复

dash.js的Vega版本包含以下修复:
  • dash.js现在会在达到重试限制时报告一次错误,而不是在每次重试时都报告错误。这与上游dash.js 5.0.0的行为相符。
要修复此问题,请从使用Dash.js播放器播放自适应内容 (DASH) 下载最新版本。

暂停播放时调整视频表面大小

以前,如果您在暂停播放时调整视频表面大小,暂停的帧不会缩放到新的大小,或者视频会短暂地出现在错误的位置之后再继续。现在,合成器会以新的大小重新呈现上一帧,因此画中画和多视图布局可以在暂停状态下正确调整大小。

在MSSE模式下搜索事件

以前,使用媒体源样本扩展 (MSSE) 模式的本机应用在IMediaSampleSourceTrack上调用seek()后不会收到seeked事件。现在,媒体管道会注册其搜索完成回调,因此IHtmlMediaElementEventListener可在搜索完成时收到timeupdate和seeked。在MSSE模式下,seek()是异步的。

TextInput焦点变化后的光标位置

以前,当TextInput位于另一个可对焦元素旁边时,使用方向键将焦点移开然后向后移动时,每次都会使光标移动一个字符。在焦点已经移动之后,按下方向键的按键事件会到达TextInput。现在,光标会停留在您离开的地方。

vpm install-async在安装后退出

以前,当您在没有--token参数的情况下运行vpm install-async时,后者会打印INSTALLATION_COMPLETED但不会退出,这会阻止自动化测试脚本。现在,该命令会在安装完成后退出。如果您已添加--token作为解决方法,则可以将其移除。

W3C媒体API参考的格式设置

W3C媒体API参考现在可以正确呈现类型链接和多行描述。这会影响MediaCapabilitiesKeySystemConfiguration、VideoProps的scalingmode属性、HTMLVideoElement和AudioPlayer。

Appium测试再次在OS 1.2及更高版本上正常运行

在某些OS 1.2内部版本中,Appium使用的自动化工具包服务无法在设备上启动。端口8383显示为正在监听,但没有进程处理请求。findElement、takeScreenshot和getPageSource等Appium命令失败,并出现socket hang up或ECONNRESET,重新启用开发者模式也无济于事。自动化工具包服务现在以开发者模式启动,因此Appium会话可以按预期连接和运行。

已知问题

如果依赖项引入RN 0.72运行时,RN 0.83应用会在启动时崩溃

如果RN 0.83应用依赖于为RN 0.72构建的库版本,则RN 0.72 运行时会加载到相同一进程中,并且该应用会在启动时崩溃,并出现SIGABRT或SIGSEGV。设备日志显示Failed to get system bundle path for: index.amzn__react-native-kepler-2.hermes.bundle。最常见的原因是@amazon-devices/kepler-ui-components 2.x,它依赖于@amazon-devices/keplerscript-native-ui-components以及其捆绑的RN 0.72运行时。 解决方法: 将@amazon-devices/kepler-ui-components升级到3.0.0或更高版本。将@amazon-devices/react-linear-gradient取代为experimental_backgroundImage样式属性(请参阅将LinearGradient取代为backgroundImage样式属性)。全新重建后,确认keplerscript-app-config.json没有列出任何RN 0.72系统捆绑包。

在Fire TV Stick HD (2026) 上播放HEVC失败

在运行OS 2.0的Fire TV Stick HD (2026)上,HEVC硬件解码器不可用。HEVC流无限期加载而不发生错误事件,并且KeplerMediaDescriptor.queryMediaCapabilitiesSync()不针对CodecMimeType.MIME_HEVC返回任何解码器。H.264播放不受影响。 解决方法: 在播放之前,查询KeplerMediaDescriptor是否支持HEVC,并在未返回任何解码器时回退到H.264流。

无法创建视频解码器时不会出现错误事件

如果媒体管道无法创建或链接视频解码器,它不会向JavaScript发送error事件。播放似乎无限期加载。要在播放前检测不支持的编解码器,请使用KeplerMediaDescriptor.queryMediaCapabilities()。

MPEG-TS中的HEVC直播HLS无法启动

在MPEG-TS片段中传输HEVC视频的直播HLS流不显示视频。时间戳偏移量会应用两次,因此样本获得负的时间戳并被丢弃,而Shaka播放器会反复向前寻找。H.264流和HEVC VOD流不受影响。 解决方法: 在Shaka播放器中,将manifest.hls.sequenceMode设置为true。

当追加操作正在进行中时removeSourceBuffer()停止响应

如果您在appendBuffer()仍在该SourceBuffer上处于进行中时调用MediaSource.removeSourceBuffer(),则该调用会阻止JavaScript线程,并且系统会因为没有响应而停止应用。该调用不会抛出InvalidStateError。 解决方法: 在移除SourceBuffer之前,请检查其updating属性是否为false,或者等待其updateend事件。

视频表面忽略像素宽高比

KeplerVideoSurfaceView使用方形像素渲染解码后的帧并忽略流的像素宽高比。变形标准清晰度内容(例如显示屏宽高比为16:9的720×576广播视频)看起来是水平压缩的。包括strech在内的所有scalingmode值都会保留缓冲区的宽高比,因此您无法在应用中更正宽高比。

大型多周期DASH清单可能会导致dash.js应用停止响应

原生XML解析器仅适用于Shaka播放器,因此dash.js使用JavaScript解析清单。对于每个广告插播都新增一个周期的直播DVR流,每次清单刷新时都会增长。大约 25 到 60 分钟后,一次刷新就可能会阻止JavaScript线程足够长的时间,以至于系统会因为没有响应而停止应用。 解决方法: 在无头JavaScript服务中运行播放器,这样清单处理就不会阻止用户界面线程。不要在应用中记录或JSON.stringify完整清单。

HMAC密钥必须正好是256位

@amazon-devices/keplercrypto中的WebCrypto.subtle.importKey()会拒绝长度不正好是256位的HMAC-SHA-256密钥,并发生NotSupportedError: A key length greater than the hash length (256 bits) is not supported。 解决方法: 对于长度超过512位的密钥,在导入密钥之前使用SHA-256对密钥进行哈希处理。这会产生相同的HMAC结果。对于其他密钥长度,在修复发布之前,请使用另一个HMAC实现。

屏幕保护程序在使用手机控制器玩游戏期间启动

屏幕保护程序会在没有本地输入的情况下在五分钟后启动,即使用户使用配对的手机作为控制器玩云串流游戏也是如此。来自手机的输入会进入云会话,因此设备不会记录用户活动。Vega不提供用于保持屏幕开启状态的API。

应用无法更改显示屏刷新率

更改DisplayManagerAPI的状态(例如requestConfigChange()和enableAutoConfigSwitch())需要com.amazon.graphics.privilege.display.manager权限,而第三方应用无法使用该权限。没有该权限,commitStates()将返回提交ID,但不会进行任何更改,也不会调用onCommitSuccess或onCommitFailure。应用无法切换输出以匹配内容帧速率,例如23.976或50 fps。

“Alexa,上一个”无法到达应用

当用户在播放期间说“Alexa,上一个”时,应用的媒体播放处理程序收不到“上一个”命令,Alexa回复说该命令不起作用。“Alexa,下一个”和“Alexa,暂停”按预期起作用。

VPN管理器不路由IPv6流量

VPN管理器API仅支持WireGuard,不通过隧道路由IPv6流量。IPv6流量会离开设备,不经过VPN,并且addRoute()拒绝IPv6 CIDR,并发生Invalid route CIDR format。我们计划在后续版本中提供IPv6支持。

PNG初始画面动画以低帧速率播放

由许多全高清PNG帧组成的启动画面动画以大约8 fps的速度播放,可能需要几秒钟才能出现。设备会在CPU上对每个PNG进行解码。 解决方法: 将帧编码为ASTC,并在assets/raw/中的SplashScreenImages.zip旁边将其打包为compressedSplashScreenImages.zip。ASTC启动动画以30 fps的速度播放。在此版本中,每次启动后,ASTC启动画面都会呈黑色,直到设备重启。

崩溃报告库无法捕获内存不足的终止情况

当内核因超出内存限制而停止应用时,进程会收到SIGKILL,因而诸如Sentry之类的崩溃报告库无法记录崩溃情况。tryGetLastTerminationData()目前仅报告“应用无响应”类的终止事件。

无法从开发者模式shell启用VoiceView

vdcm set "com.amazon.devconf/system/accessibility/VoiceViewEnabled" "ENABLED"在开发者模式shell中失败,并发生No permission for operation。要打开VoiceView,请改用设备的无障碍功能设置。

ifconfig在开发者模式shell中不起作用

开发者模式shell没有/proc/net的访问权限,因此ifconfig不返回网络信息。要查找设备的IP地址,以便通过TCP/IP使用VDA,请在设备上选择Settings(设置)> Network(网络)。

使用@types/node 26时,TypeScript 4项目构建失败

如果您的项目使用TypeScript 4并直接或通过其他依赖项安装@types/node 26.x,则类型检查和构建将失败,并在@types/node声明文件中出现错误。@types/node 26.x使用TypeScript 4不支持的TypeScript语法。 @types/node是一个由社区维护的程序包,不是Vega SDK的一部分。Vega SDK不会设置您的@types/node版本,因此此问题可能会影响任何SDK 版本上的项目。 解决方法: 将您devDependencies中的typescript更新为版本5,例如5.8.3。如果还无法升级TypeScript,请在devDependencies或overrides中将@types/node固定到26之前的版本。然后运行npm install并重建。

操作系统内部版本

Vega OS 2.0在每台支持的设备上都有不同的内部版本号。使用下表确认您的设备运行的是OS 2.0内部版本。要查看您的设备软件版本,请前往** My Fire TV**(我的Fire TV)> About(关于)。
最后修改于 2026年10月28日