为您的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的总体可用性和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创建的项目上,第一次运行会从源代码控制的清单中删除以下行:
深度导入不再在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应用不受影响。
@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秒,每次运行最多可能需要五分钟。
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。
@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的行为相符。
暂停播放时调整视频表面大小
以前,如果您在暂停播放时调整视频表面大小,暂停的帧不会缩放到新的大小,或者视频会短暂地出现在错误的位置之后再继续。现在,合成器会以新的大小重新呈现上一帧,因此画中画和多视图布局可以在暂停状态下正确调整大小。在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并重建。

