Vega SDK CLI参考

Vega SDK包含命令行界面 (CLI)，让您可以使用命令提示符构建应用，并运行Vega虚拟设备 (VVD)。运行命令时，将所有占位符替换为实际值，以免报错。例如，将<应用名称>、<公司名称.应用名称>和<项目根目录>替换为您的应用名称、公司名称和项目目录路径。请勿使用amazon作为您的公司名称或程序包ID。

本页阐述了Vega CLI命令和示例。

帮助和版本选项

要打印已安装的Vega CLI版本：

vega --version

缩写形式为vega -v。报告问题时需包含此版本，并在CI管道中通过此版本确认构建所用的CLI。要查看项目构建时所用的SDK版本，请参阅管理SDK版本。

要浏览所有Vega命令的选项：

vega--help 

要获取有关特定命令的帮助，可运行以下命令：

vega <command> --help

例如，要查看vega build命令的所有选项，可运行以下命令：

vega build --help

退出代码和错误输出

Vega CLI命令成功时返回退出代码0，失败时返回非零退出代码。错误消息会写入stderr。

常用命令

npx react-native build-vega

使用npx react-native build-vega命令来编译您的应用并生成vpkg。

要构建应用，可运行以下命令：

npm install
npx react-native build-vega

vega clean

要移除<项目根目录>/build文件夹中生成的工件，可运行以下命令：

vega clean

vega project list-templates

要查看可用于创建示例应用的可用JavaScript和Turbo模块模板，可运行以下命令：

vega project list-templates

输出示例：

vega project list-templates

可用模板：
helloWorld： 使用此项目模板创建新应用（目标版本为RN v0.83）
helloWorld-rn72： 使用此项目模板创建新应用（目标版本为RN v0.72）
basic-turbo-module： 一个Turbo模块示例，内含用于调用自有原生逻辑的存根。
idl-turbo-module： 一个Turbo模块示例，使用IDL中定义的原生操作系统API。
vegaWebview： 适用于Vega应用的Webview模板

vega project generate

要创建Vega项目，可使用带所需参数的vega project generate命令。

要创建新应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega project generate --template helloWorld --name "<应用名称>" --packageId "com.<公司名称>.<应用名称>" --outputDir "<应用名称>"

以下是命令中不同组件的明细：

• vega project generate - 生成Vega应用。

• --template - 设置Vega应用或Turbo模块模板，您可以用vega project list-templates命令找到该模板。示例中使用的是helloWorld模板。

• --name - 为新应用或Turbo模块设置名称。名称不能包含空格或特殊字符。将<应用名称>替换为所需的新应用名称。

• --packageId - 设置适用于Vega的React Native应用中（而非Turbo模块中）所需manifest.toml的程序包ID。将<公司名称>替换为您的公司的名称，将<应用名称>替换为您的应用的名称。

• --outputDir（可选）- 设置新应用文件的输出目录。将<应用名称>替换为您的应用的实际名称。

当您遵循此格式时，该命令会显示新项目的路径。

vega run-app

要安装和运行您的应用，可运行以下命令：

vega run-app <VPKG路径> <应用ID> -d <设备>

以下命令结合了vega device install-app和vega device launch-app。

对于VVD：

复制代码 已复制到剪贴板。

vega run-app <VPKG路径> <应用ID> -d VirtualDevice

对于Fire TV：

复制代码 已复制到剪贴板。

vega run-app <VPKG路径> <应用ID> -d <DSN>

例如，要在Mac M系列计算机上运行名为sampleapp的应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega run-app build/aarch64-release/sampleapp_aarch64.vpkg com.amazondeveloper.sampleapp.main -d VirtualDevice

项目兼容性命令

vega project兼容性命令负责管理应用支持的操作系统版本。这些命令可解析兼容的程序包版本、将项目重新对齐到操作系统版本目标、验证配置，并重新生成清单模块条目。有关这些命令背后的概念，请参阅操作系统目标版本。

vega project install

要将兼容操作系统版本的@amazon-devices/*程序包解析到package.json中：

vega project install [packages..] [options]

install和install --fix既不会下载程序包，也不会更改node_modules文件夹。两者均能解析兼容版本并将其写入package.json。两者的作用域不同：

• vega project install <程序包..> - 如果所有兼容性检查均通过，则会将指定的@amazon-devices/*程序包作为依赖项，添加到package.json中。只有此形式可新增依赖项。

• vega project install --fix - 将package.json中的现有@amazon-devices/*版本全部重新对齐到兼容性配置文件中。此形式不会新增程序包。

两者均为可选项。省略--os-version和--rn-version时，该命令会通过项目的manifest.toml和package.json读取。默认关闭--fix和--dry-run。

--os-min是写入manifest.toml，而非package.json的唯一选项，作用范围比其它选项更小：

• 仅在搭配--fix使用时生效。单独运行vega project install --fix或install <程序包>均不会写入min。

• 通过--os-version传递。如果项目中缺少 [os.version] 部分，则install无法解析目标，从而导致操作失败并报错缺少操作系统版本，且不会写入任何内容。

• 在缺少 [os.version] 部分的项目中同时使用这两个标记，install可创建该部分、设置min、写入target，并根据📝 在manifest.toml中设置[os.version] min = "<v>"进行确认。

• 若已存在 [os.version]，则此形式仅写入min，不更改target。旧版 [os] 部分可用作现有部分。要更改target，请运行vega project update-manifest。

例如，要将项目中操作系统提供的程序包逐一重新对齐：

vega project install --fix

输出示例：

📦 已安装的程序包，适用于操作系统版本1.2 + RN 0.72

程序包：
  📦 @amazon-devices/kepler-file-system@1.2.0（已修复）
  ✓ @amazon-devices/kepler-camera@1.0.0（当前）

💡 后续步骤：
  • npm install — 安装已更新的依赖项
  • vega project doctor — 验证操作系统版本的兼容性
  • 构建您的应用（npx react-native build-vega或您的构建脚本）

随后可选择是否运行vega project doctor（建议运行）。install --fix会解析版本，doctor则会验证结果，并运行源码级操作系统lint。有关详细信息，请参阅vega project doctor。

借助--dry-run，命令可预览解析结果，无需写入任何更改项，同时标头会变为🔍 试运行—不作任何更改。

vega project update

要将项目中的npm程序包与清单重新对齐到操作系统版本目标：

vega project update [options]

update仅重新对齐您应用当前依赖的程序包版本。此操作会将这些程序包逐一升级到可兼容操作系统目标的版本，其余程序包则保持不变。要新增依赖项，请执行vega project install。

两者均为可选项。省略时，命令会读取项目manifest.toml中的--os-version、--os-min和--rn-version，默认关闭--dry-run。

update和install --fix均能将package.json中现有的@amazon-devices/*版本重新对齐到兼容性配置文件，且两者均可接受--os-version和--os-min。使用install --fix进行常规设置与重新对齐，并创建尚不存在的 [os.version] 部分。如果想在写入更改项之前先预览更改计划，可使用update，因为--dry-run会逐一报告程序包的版本变化。

例如，要预览针对manifest.toml中目标版本的重新对齐效果：

vega project update --dry-run

输出示例：

📋 更新计划，适用于操作系统版本1.2 + RN 0.72：

  🔄 @amazon-devices/kepler-file-system (1.1.0 → 1.2.0)
  ✓ @amazon-devices/kepler-camera (1.2.0)
  ✓ @amazon-devices/kepler-lifecycle (1.2.0)

1个程序包待更新。

🔍 试运行—不作任何更改。在不使用--dry-run的情况下运行，以应用更改项。

在计划中，🔄图标表示程序包已更改，✓图标则表示程序包未更改。无需进行任何更改时，此命令会报告✅ 所有程序包均为最新版本。

vega project doctor

要验证项目操作系统版本的兼容性，包括配置、依赖项和lint规则：

vega project doctor [options]

两者均为可选项。省略时，此命令会读取项目中的值。仅在需要覆盖项目已有配置的情况下传递。

doctor会运行以下检查项：

• SDK兼容性清单已存在。

• 项目配置已解析。

• [os.version].min和[os.version].target均为正式发布的有效操作系统版本。

• [os.version].min版本不高于[os.version].target版本。

• 您的@amazon-devices/*依赖项版本与SDK配置文件相匹配。

• manifest.toml中已存在操作系统版本模块条目。

• 源码级操作系统版本lint规则no-unguarded-os-api已通过验证。

no-unguarded-os-api规则会标记每一条API引用，其源自高于[os.version].min的操作系统版本。位于isPresentOnOS()保护范围内的引用，或import前一行带有// @os-version-ok注释的引用，均可通过检查。该规则报告的是使用位置，而非import行。

输出示例：

🩺 Project Doctor

  ✅ 操作系统版本有效：min=1.2, target=1.2
  ✅ os.min ≤ os.target: 1.2 ≤ 1.2
  ✅ 依赖项： 5个程序包均与清单匹配
  ✅ os.min中的needs.module： os.min中的needs模块全部可用
  ✅ 操作系统版本lint： 未发现操作系统版本问题

✅ 关键检查项均已通过。

截至Vega SDK 0.24，操作系统1.2是唯一正式发布的版本，因此min和target的值均设为1.2。lint会报告未发现操作系统版本问题，原因在于min之后的版本未引用任何API，因此无需进行任何保护。后续发布更高版本的操作系统时，如果设置的min低于target，则lint会标记每一条未经保护的API引用，其源自在min之后发布的版本。此规则会以file:line:column rule-id格式报告每个问题，并在下方缩进显示详情。摘要内容会变为❌ 1项检查未通过，doctor则会以非零状态退出。

在结果中，✅图标表示检查通过，⚠️表示警告，❌则表示失败。如有任何严重级别为“失败”的检查项未通过，vega project doctor会以非零状态退出，因此可将其用作CI管道中的门禁。有关更多信息，请参阅将Vega SDK集成到CI管道中。

vega project update-manifest

要通过 [os.version] 配置在manifest.toml中重新生成操作系统版本模块条目：

vega project update-manifest [options]

此命令仅写入操作系统版本条目，不会写入@amazon-devices/*程序包条目，后者在构建时会重新生成。写入条目如下：

• 一条适用于 [os.version].min的 [[needs.module]] 条目，格式为/com.amazon.vega.os@IVega_<min>。您的应用无法安装在版本低于min的设备上。

• 一条适用于min以上所有操作系统版本（最高为 [os.version].target）的 [[wants.module]] 条目，格式为/com.amazon.vega.os@IVega_<v>。当min与target的版本相同时，不会存在wants。

在命令行上传递操作系统版本时，需同时传递--os-min和--os-version。min定义needs模块，target定义wants上限，两者共同决定最终生成的模块条目。同时省略两者时，命令会从manifest.toml中读取这两个参数。请同时传递这两个参数。

例如，要为操作系统目标版本为1.2的项目生成模块条目：

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

输出示例：

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

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

运行--dry-run命令会打印已生成的TOML，但不会写入。有关清单字段的定义，请参阅清单 [os.version] 部分。有关needs和wants的更多信息，请参阅清单 [needs] 部分和清单 [wants] 部分。

设备命令

Vega CLI设备命令接口为您提供了一种与物理设备和Vega虚拟设备进行交互的方式。必须在路径上安装VDA并使其可用，设备命令才能起作用。

一般命令格式为：

vega device <命令> [参数]

要查看所有可用的设备命令，可运行以下命令：

vega device --help

vega device copy-from

要将设备文件复制到主机计算机，可运行以下命令：

复制代码 已复制到剪贴板。

vega device copy-from --device <设备序列号> --source <文件或目录> --destination <文件或目录>

vega device copy-logs

要从设备检索工件文件，可运行以下命令：

复制代码 已复制到剪贴板。

vega device copy-logs --device <设备名称> --artifact <工件名称> --directory <文件的目录>

vega device copy-to

要将主机文件复制到设备，可运行以下命令：

复制代码 已复制到剪贴板。

vega device copy-to --device <设备名称> --source <文件或目录> --destination <文件或目录>

vega device get-log-info

要从设备检索日志信息，可运行以下命令：

复制代码 已复制到剪贴板。

vega device get-log-info --device <设备名称>

vega设备信息

要检索JSON格式的设备元数据，包括设备类型、操作系统版本、主机名、架构、配置文件、产品名称、内部版本描述、设备是模拟设备还是物理设备以及开发者模式状态，可运行以下命令：

复制代码 已复制到剪贴板。

vega device info --device <device name>

输出示例：

{
  "idme": "ABCDEFG999999",
  "os": "OS",
  "hostname": "hostname",
  "architecture": "aarch64",
  "profile": "tv",
  "product": "vvrp-tv-arm64",
  "buildDescription": "OS 1.2",
  "simulated": true,
  "inDeveloperMode": true
}

vega device install-app

要在设备或VVD上安装应用，请先为应用包添加路径参数 (-p)。路径遵循以下语法：build/<架构>-<构建类型>/<应用名称>_<架构>.vpkg.

例如，如果sampleapp在Mac x86计算机上运行，可运行以下命令：

复制代码 已复制到剪贴板。

vega device install-app -p build/x86_64-release/sampleapp_x86_64.vpkg --device <设备名称>

要自动在目录中找到正确的.vpkg并安装它，可运行以下命令：

vega device install-app --dir .

要指定debug构建类型，可运行以下命令：

vega device install-app --dir . -b Debug

要指定release构建类型，可运行以下命令：

vega device install-app --dir . -b Release

vega device installed-apps

要列出设备上安装的应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device installed-apps --device <设备名称>

例如，要查看VVD上安装的所有应用的列表：

vega device installed-apps --device VirtualDevice

vega device installed-packages

要列出设备上安装的所有程序包，可运行以下命令：

复制代码 已复制到剪贴板。

vega device installed-packages --device <设备名称>

例如，要查看VVD上安装的所有程序包的列表：

vega device installed-packages --device VirtualDevice

vega device is-app-installed

要使用应用名称检查应用是否已安装，可运行以下命令：

复制代码 已复制到剪贴板。

vega device is-app-installed --device <设备名称> --appName <应用名称> 

要使用项目目录检查应用是否已安装，可运行以下命令：

vega device is-app-installed --device <设备名称> --directory <项目目录>

vega device is-app-running

要使用应用名称检查应用是否在设备上运行，可运行以下命令：

复制代码 已复制到剪贴板。

vega device is-app-running --device <设备名称> --appName <应用名称> 

要使用项目目录检查应用是否在设备上运行，可运行以下命令：

vega device is-app-running --device <设备名称> --directory <项目目录>

vega device is-connected

要检查特定设备的连接状态，可运行以下命令：

复制代码 已复制到剪贴板。

vega device is-connected --device <设备名称>

示例：

vega device is-connected --device GXX2A1234567890A

连接时的输出：

Device GXX2A1234567890A is connected

未连接时的输出：

Device GXX2A1234567890A is not connected

vega device launch-app

要使用应用名称在设备上启动应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device launch-app --device <设备名称> --appName <应用名称> 

要使用项目目录在设备上启动应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device launch-app --device <设备名称> --directory <项目目录>

vega device list

要列出已连接的设备（Fire TV Stick和VVD）：

vega device list

VVD会显示为： VirtualDevice : tv - architecture - OS type - hostname

示例输出，包含已连接Fire TV Stick (GXXXXXXXXXXXXXXX) 和正在运行的VVD：

GXXXXXXXXXXXXXXX: A1ZZ32RVTQ796E 
VirtualDevice : tv - x86_64 - OS - yourhostname

vega device reboot

要重启给定设备，可运行以下命令：

复制代码 已复制到剪贴板。

vega device reboot --device <设备名称>

vega device run-cmd

要在特定设备上运行命令，可运行以下命令：

复制代码 已复制到剪贴板。

vega device run-cmd --device <设备名称> --command '<要运行的命令>'

vega device running-apps

要列出正在设备上运行的所有应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device running-apps --device <设备名称>

例如，要查看VVD上正在运行的所有应用的列表：

复制代码 已复制到剪贴板。

vega device running-apps --device VirtualDevice

vega device shell

要在设备上启动shell会话，可运行以下命令：

复制代码 已复制到剪贴板。

vega device shell --device <设备名称>

vega device start-log-stream

要开始从设备流式传输日志，可运行以下命令：

复制代码 已复制到剪贴板。

vega device start-log-stream --device <设备名称>

vega device stop-log-stream

要停止从设备流式传输日志，可运行以下命令：

复制代码 已复制到剪贴板。

vega device stop-log-stream --device <设备名称>

vega device start-port-forwarding

要启动设备的正向或反向端口转发，可运行以下命令：

复制代码 已复制到剪贴板。

vega device start-port-forwarding --device <设备名称> --port <端口号> --forward <true|false>

vega device stop-port-forwarding

要停止设备的正向或反向端口转发，可运行以下命令：

复制代码 已复制到剪贴板。

vega device stop-port-forwarding --device <设备名称> --port <端口号> --forward <true|false>

vega device terminate-app

要使用应用名称终止设备上的应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device terminate-app --device <设备名称> --appName <应用名称> 

要使用项目目录终止设备上的应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device terminate-app --device <设备名称> --directory <项目目录>

示例：

vega device terminate-app --appName com.amazondeveloper.sampleapp.main --device VirtualDevice

// 输出 
强制停止pkg: com.amazondeveloper.sampleapp

vega device uninstall-app

要使用应用名称从设备上卸载应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device uninstall-app --device <设备名称> --appName <应用名称> 

要使用项目目录在设备上卸载应用，可运行以下命令：

复制代码 已复制到剪贴板。

vega device uninstall-app --device <设备名称> --appName <应用名称> --directory <项目目录>

示例：

vega device uninstall-app --appName com.amazondeveloper.sampleapp.main --device VirtualDevice

// 输出
正在卸载'com.amazondeveloper.sampleapp' ...成功 

Vega虚拟设备命令

vega virtual-device status

要查询VVD状态：

vega virtual-device status

vega virtual-device start

要重启VVD：

vega virtual-device start

终端显示以下消息：

Launching virtual device（正在启动虚拟设备）。
Waiting for virtual device to boot.
Virtual device ready.

vega virtual-device stop

要停止VVD：

vega virtual-device stop

相关主题

• 解决Vega扩展程序和CLI问题
• Vega Studio命令

Last updated: 2026年8月19日