将Fire OS应用移植到Vega
应用移植是一种AI辅助工作流程，可将您现有的Fire OS应用迁移到Vega应用。它使用用于AI的Amazon Devices Builder Tools分析您的源代码、生成迁移计划并生成一个可运行的Vega应用。当您希望将现有Fire OS应用迁移到Vega，而又不想进行逐屏手动重写时，可使用此工具。
本页面说明应用移植支持哪些内容、其工作方式以及如何运行。
应用移植的功能
应用移植可自动将Fire OS应用转换为Vega应用。它处理四条迁移路径。
| 源应用类型 | 输出 |
|---|---|
| Fire OS WebView应用 | Vega WebView应用 |
| Fire OS React Native应用 | 适用于Vega的React Native应用 |
| Fire OS原生应用（Java或Kotlin） | 适用于Vega的React Native应用 |
| Web URL（无源代码） | Vega WebView应用 |
您无需自行确定应用类型。应用移植会检查您的项目结构，检测其属于哪种受支持的类型，并遵循匹配的路径。您可以在提示词中指定应用类型以加快检测速度，但应用移植仍会根据您的项目结构进行验证。如果不确定，它会在继续之前询问您。
工作方式
应用移植分为六个阶段。
- 第1阶段： 验证 - 应用移植检测您的应用类型、收集元数据（程序包名和应用名），并验证项目结构。
- 第2阶段： 规划 - 应用移植逐文件扫描您的源代码，将Fire OS API和模式映射到其Vega等效项，并生成迁移指南。
- 第3阶段： 执行 - 应用移植根据相应的模板搭建Vega项目，并应用迁移指南来生成应用的代码。
- 第4阶段： 构建和验证 - 应用移植构建Vega应用、运行迁移验证测试、将其安装到连接的设备上并启动。
- 第5阶段： 引导式AI审查 - 应用移植会打开一个交互式会话，您可以在其中对应用进行设备端测试，并报告问题以供AI代理诊断和修复。
- 第6阶段： 性能比较（可选）- 应用移植会根据指南阈值或您原始的Fire OS应用，对应用启动时间、用户界面流畅度和内存使用情况进行基准测试。
在整个过程中，应用移植会将无法自动迁移的所有内容记录在生成项目的NextSteps.md文件中。
先决条件
在开始应用移植之前，请确保您已具备以下条件。
- 已为您的AI代理安装并配置了Amazon Devices Builder Tools。
- Vega SDK v0.22或更高版本。请参阅安装Vega SDK。
- 用于第4阶段及之后的Vega设备。如果未连接物理设备，应用移植会启动Vega虚拟设备 (VVD)，以免流程受阻。建议使用物理设备，因为VVD不支持屏幕截图和性能工具分析。
- 您的Fire OS应用源代码，或要封装的Web URL。
- Fire OS设备（可选，用于在第6阶段进行Fire OS与Vega的性能比较）。
开始应用移植
要开始应用移植，请在AI代理的聊天中使用以下提示词之一。
Port my TV app to Vega（将我的电视应用移植到Vega）
如需更具体地指定应用类型，请使用以下提示词之一。
Convert my Fire OS WebView app to a Vega Web App（将我的Fire OS WebView应用转换为Vega Web应用）
Port my Fire OS React Native app to React Native for Vega（将我的Fire OS React Native应用移植到适用于Vega的React Native）
代理会询问您要转换什么内容以及在哪里创建输出。请提供以下内容之一。
- Fire OS应用源代码的路径，可让代理自动检测应用类型。
- Web URL，代理会使用它创建一个封装该URL的Vega WebView应用。
然后，代理会依次执行六个阶段。您在第5阶段（引导式审查）进行交互，以验证功能并报告问题。
npm install失败在第3阶段（执行）中很常见，通常由版本冲突或NPM注册表令牌过期引起。有关修复方法，请参见故障排除。支持的迁移路径
应用移植支持以下迁移路径。
将Fire OS WebView应用迁移到Vega WebView应用
应用移植将基于WebView（HTML5混合）的应用（其用户界面作为Web内容在WebView内运行）转换为Vega WebView应用。检测会查找JavaScript到原生桥接、加载的打包网页应用，或将<WebView>作为主屏幕界面。仅在少数屏幕上使用WebView的应用会被视为原生应用，而非WebView应用。代理会从您的源代码中提取加载的URL、设置和JavaScript接口。
将Web URL迁移到Vega WebView应用
应用移植会创建一个加载指定URL的新Vega WebView应用。您无需现有源代码。您也可以指向参考代码库（您现有的Fire OS应用或非Fire OS包装器），以便代理扫描其中的集成细节，例如深层链接、身份验证或广告SDK。
将Fire OS React Native应用迁移到适用于Vega的React Native应用
应用移植将专为Fire OS构建的React Native应用（包括基于Expo的电视应用）转换为适用于Vega的React Native应用。代理会将您的React Native组件和第三方库映射到其Vega等效项。
将Fire OS原生应用（Java或Kotlin）迁移到适用于Vega的React Native应用
应用移植将原生Android应用（Activity、Fragment和ViewModel）转换为适用于Vega的React Native应用。此路径是从Java或Kotlin到React Native的完全重写，因此生成后需要最多的人工审查。代理会将Android UI组件和API映射到React Native等效项，并将没有Vega等效项的API记录在NextSteps.md中。
了解输出
应用移植完成后，生成的Vega应用目录包含以下内容。
- 应用源代码。 基于相应模板的可构建Vega项目。
- migration_guide.md。 代理在第2阶段生成任何代码之前编写的计划。它会将原始应用中的每个屏幕、功能和资产映射到其Vega等效项。应用是根据此文件构建的，因此这里缺失的任何内容在应用中也会缺失。在第2阶段（规划）之后、第3阶段（执行）之前对其进行审查，以便及早发现缺口。
- NextSteps.md。 记录需要人工处理的缺口的文件，包括：
- 没有Vega等效项的API或原生模块。
- 第4阶段中遇到的构建错误。
- 迁移验证测试结果。
- 性能基线或回归说明（如果您选择了第6阶段）。
- 涵盖所有已迁移集成的测试清单。
工作流程完成后，请务必查看NextSteps.md。
限制
应用移植处于Beta阶段，存在以下限制。
- 自定义原生模块。 应用移植支持自定义Turbo模块。它只会在
NextSteps.md中标记那些无法自信映射或没有Vega等效项的原生模块，以供人工处理。 - 不受支持的第三方库。 原生代码没有Vega等效项的库无法自动迁移。该工作流程会检查您的依赖项，并标记任何不受支持的内容，供您手动处理。
- 复杂的自定义视图。 使用Canvas绘制的自定义View子类（自定义小部件、图表、绘图或游戏界面）没有直接的React Native等效项，会被标记为需要手动实现。标准布局、小部件和列表会自动转换。
- Fire OS和Android API。 与Fire OS或Android API的深度集成，若超出知识库覆盖范围，会被标记为需要手动解决。
- 代码质量。 生成的代码提供了可用的起点，但可能不符合生产编码标准。计划进行一轮代码审查。
故障排除
| 问题 | 解决方案 |
|---|---|
| 代理无法确定应用类型。 | 验证源路径指向项目根目录（package.json或AndroidManifest.xml所在的位置）。 |
vega: command not found。 |
请参阅安装Vega SDK。 |
npm install因版本冲突而失败。 |
运行npm install --legacy-peer-deps --userconfig .npmrc，或检查迁移指南中是否存在版本不匹配。 |
npm install因身份验证令牌错误而失败。 |
运行harmony npm刷新NPM注册表凭据，然后重试。 |
| 应用构建成功但显示空白屏幕。 | 对于WebView应用，请验证com.amazon.webview.renderer_service是否位于manifest.toml的[wants]部分中。 |
| 生成的代码与预期不符。 | 查看第2阶段生成的迁移指南。确认您的应用符合支持的迁移路径。 |
如需更多故障排除信息，请参阅应用迁移工作流未产生预期结果。
一旦NextSteps.md中没有剩余的阻塞项，您的Vega应用就可以进行进一步测试和认证了。
相关主题
- 用于AI的Amazon Devices Builder Tools入门
- Vega模块解析器预设
- 将第三方库移植到Vega
- 使用模板构建新应用
- 解决用于AI的Amazon Devices Builder Tools问题
Last updated: 2026年9月30日
