本指南介绍了如何使用 gcloud beta device-run CLI 运行独立的 Android 可执行文件，以及如何在 Google Cloud 控制台中查找结果。它假定您拥有一个 Google Cloud 账号和项目。
如果您要从 Firebase Test Lab 迁移到 Developer Device Platform，请参阅我们的迁移指南、命令和标志转换以及 AI 智能体的迁移技能。
如需使用此 Google Cloud CLI，您需要提供 Google Cloud 项目 ID。如需查看命令摘要，请参阅 gcloud beta device-run。
准备工作
这些步骤假定您已完成以下操作：
- 创建了 Google Cloud 项目。
- 按照快速入门中的说明设置 Developer Device Platform。
- 在终端中使用
gcloud进行了身份验证。 - 查看了 Device Run 概览，了解一般信息。
- 准备好独立的 Android 可执行文件（例如已编译的 C++ 二进制文件、基准测试运行程序或 shell 脚本）。
第 1 步：配置可执行文件运行
Android 可执行文件的选项
- 多台设备：如需在多台设备上运行同一可执行文件，请提供
--device标志，后跟多个设备 ID（以英文逗号分隔，例如--device shiba-34,tokay-36），或提供多个--device标志，每个标志指定一个不同的设备 ID（例如--device shiba-34 --device tokay-36）。 - 将文件推送到设备：在执行之前，使用
--other-files-to-push=SOURCE=DEST,...将其他文件（例如机器学习模型权重、测试输入或.so共享库）推送到设备。SOURCE支持本地路径和 Cloud Storage (gs://...) 路径，DEST是设备上的目标路径。 - 从设备拉取文件：执行完成后，使用
--paths-to-pull=DEVICE_PATH,...从设备拉取生成的文件或目录。 - 自定义 Cloud Storage 存储桶：使用
--bucket-name=指定现有 Cloud Storage 存储桶名称（不带gs://架构或路径）。如果您未指定存储桶，Google Cloud CLI 会使用或创建名为PROJECT_ID-devicerun的默认存储桶。 - 不可靠的测试重试次数：设置每个作业或分片处理不可靠测试的最大尝试次数：
--flaky-test-attempts=3（默认值为1次尝试）。 - 设备环境和诊断：配置设备屏幕方向（
--orientation=portrait或landscape）、语言区域 (--locale=en-US)、模拟 GPS 位置 (--coordinates=LATITUDE,LONGITUDE)、屏幕录像（--video=always或on-failure）、dumpsys收集（--dumpsys=always或on-failure）或bugreport收集（--bugreport=always或on-failure）。 - 标签：使用
--labels=KEY=VALUE,...将用户定义的键值对标签附加到会话。 - 可执行文件参数：使用
--executable-args=ARG,...将命令行参数作为逗号分隔列表传递给可执行文件，或通过重复该标志来传递。每个元素都会成为一个参数，因此请以逗号分隔的形式重写以空格分隔的命令行（例如--executable-args="--input=a.file,--threads=4"）。如需传递本身包含逗号的参数，请在值的前面加上^SEP^以指定其他分隔符（例如--executable-args="^;^--shape=1,224,224,3;--threads=4"）。 - 环境变量：使用
--executable-env-vars=KEY=VALUE,...为设备上的可执行进程设置环境变量（例如--executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib）。 - 可执行文件超时：限制可执行文件的执行时长：
--executable-timeout=10m（有效范围为1m到3h，默认值为5m，不包括设备准备和清理时间）。
同步和异步运行
默认情况下，提交命令是阻塞（同步）的。它会等待可执行文件完成，并输出结果摘要表。
如需在将文件上传到 Cloud Storage 后立即提交会话并返回，请添加 --async 标志：
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--async
此操作会立即返回会话 ID。然后，您可以使用 sessions wait 命令等待其完成：
gcloud beta device-run sessions wait SESSION_ID
该命令会一直处于阻塞状态，直到作业完成。
多个设备
如需在多台设备上运行同一可执行文件，请提供 --device 标志，并使用英文逗号分隔多个设备 ID，或提供多个 --device 标志，每个标志指定一个不同的设备 ID。
gcloud beta device-run sessions submit android-executable \
--device shiba-34,tokay-36 \
--executable ./MY_EXECUTABLE
或：
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--device tokay-36 \
--executable ./MY_EXECUTABLE
可执行文件超时
限制可执行文件的运行时间：
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--executable-timeout=10m
运行次数的有效范围为 1m 到 3h，默认值为 5m。
第 2 步：选择设备
使用 device-run CLI，Android 可执行文件可以在可用的实体设备和虚拟设备上运行。如需查看可用设备的完整列表，请访问交互式设备目录或运行以下命令：
gcloud beta device-run devices list
输出示例：
ID MAKE NAME MODEL FORM OS_VERSION CAPACITY AVAILABILITY PRODUCTS
tegu-35 Google Pixel 9a tegu PHYSICAL 35 MEDIUM LOW Automation, Streaming
tokay-34 Google Pixel 9 tokay PHYSICAL 34 HIGH HIGH Automation, Streaming
请参阅设备目录，了解如何过滤此列表。如需在执行时定位到特定设备，请在 submit 命令中使用其对应的 ID（例如 tegu-35）。
第 3 步：运行可执行文件
提交独立的 Android 可执行文件。
如需直接在 Android 设备上运行独立可执行文件（例如已编译的 C++ 二进制文件、设备端机器学习基准运行程序 [如 LiteRT] 或 shell 脚本），而无需将其打包到 APK 中，请使用 sessions submit
android-executable 命令。
Android 可执行文件需要以下标志：
- 设备：使用
--device指定设备：--device shiba-35 - 可执行文件：使用
--executable指定可执行文件的本地或 Cloud Storage 路径：--executable /path/to/my_executable
如需运行可执行文件，请发出类似于以下内容的命令，并使用您自己的设备 ID 和可执行文件路径：
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--executable /path/to/my_executable \
--executable-args="--input=/data/local/tmp/file.name,--threads=4" \
--other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
--paths-to-pull=/data/local/tmp/output
您可以在 Cloud Storage 路径（例如 gs://BUCKET_NAME/automation/sessions/SESSION_ID/）中找到作业的结果报告文件夹。请参阅命令输出中的链接，如下所示：https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/。
第 4 步：探索和管理可执行文件运行
对于 sessions submit android-executable 命令的异步和同步模式，您可以使用 sessions describe 命令在执行期间查询作业状态，或在作业完成后获取结果：
gcloud beta device-run sessions describe SESSION_ID
输出会总结执行结果，并提供指向Google Cloud 控制台中的结果的链接。例如：
Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 all FAILED: 2 test cases failed, 5 passed
使用以下命令列出所有正在运行和已完成的会话：
gcloud beta device-run sessions list
您将收到包含项目中会话列表的输出，如下所示：
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
session-911d0763 2026-07-09T00:39:02.051Z DONE
session-4e943fea 2026-07-15T23:08:32.252Z DONE
session-0132e458 2026-08-20T18:33:19.751Z DONE
session-1077f07b 2026-07-28T22:35:43.848Z DONE
session-71b054c6 2026-07-15T01:15:41.643Z DONE
session-4f8b2e45 2026-08-06T23:11:56.161Z DONE
sessions list 命令支持所有标准 Google Cloud CLI 标志选项。例如：
gcloud beta device-run sessions list --limit 5
这会产生类似于以下内容的结果：
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce 2026-07-03T05:10:58.015Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
或者，如需查找所有正在运行的会话，请运行以下命令：
gcloud beta device-run sessions list --filter RUNNING
假设您有正在运行的会话，您会看到类似以下内容的结果：
SESSION_ID START_TIME STATE
session-d7ff8b81 RUNNING
否则，您将收到 Listed 0 items.
如需取消正在运行的会话，请使用您的会话 ID 运行以下命令：
gcloud beta device-run sessions cancel SESSION_ID
该命令会立即返回，因为会话仅标记为取消。取消操作会在后端异步进行。
如果会话已完成，则仅输出当前状态。 请求取消已完成的会话不会导致错误。
后续步骤
接下来，运行 Android 插桩测试或查找和分析日志。