@expo-harmony/cli 55.0.26-harmony.11 → 55.0.26-harmony.12

package/README.md

@@ -80,7 +80,7 @@ npx expo-harmony prebuild --check
 
 `--clean` 删除原生工程后重新生成。如果工程缺少 CNG 清单或模板标记，或者目录是符号链接、位于项目之外，命令会拒绝删除。
 
-`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能与其他会修改工程的选项一起使用。
+`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0，有差异时列出变更并以退出码 2 结束。这个选项不能和会修改工程的选项一起使用。
 
 ## Build
 
@@ -94,7 +94,7 @@ npx expo-harmony build --sync
 
 默认构建 Debug 版本。使用 `--variant release` 构建 Release 版本时，命令会将 JS Bundle 和资源打包进应用。
 
-项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新；有差异时停止构建，可以使用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
+项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新，有差异就停止构建，可以用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
 
 ## Doctor
 
@@ -154,7 +154,7 @@ npx expo-harmony run \
   --port 8081
 ```
 
-`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程；如果工程不存在，会先运行 prebuild。
+`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程，工程不存在时先运行 prebuild。
 
 常用选项：
 
@@ -169,7 +169,7 @@ npx expo-harmony run \
 
 Debug 模式下，如果 Metro 由这个命令启动，日志会显示在当前终端，按 Ctrl+C 退出。
 
-未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器；如果也没有正在启动的模拟器，就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
+未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器，没有的话就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
 
 按名称选择或自动启动模拟器时，CLI 会等待模拟器开机并连接 HDC，最多等待 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
 
@@ -191,6 +191,28 @@ CLI 先读取环境变量指定的工具路径，再查找 DevEco Studio 的安
 | `EXPO_HARMONY_NODE` | 指定原生构建过程中运行 Expo Harmony CLI 的 Node.js 路径，要求 Node.js 20 或更高版本 |
 | `DEVECO_SDK_HOME`、`HARMONY_HOME` 或 `OHOS_SDK_HOME` | 指定 HarmonyOS SDK 根目录 |
 
+### 超时
+
+OHPM 安装、Hvigor 构建、等待模拟器这些步骤都有超时，默认值见下表，可以通过环境变量覆盖。变量名为 `EXPO_HARMONY_<操作名大写下划线>_TIMEOUT_MS`，单位为毫秒，例如 `EXPO_HARMONY_OHPM_INSTALL_TIMEOUT_MS`。设置成 0、负数或无法解析的值时，这个变量会被忽略，并给出警告。
+
+| 环境变量 | 对应操作 | 默认值 |
+| --- | --- | --- |
+| `EXPO_HARMONY_OHPM_INSTALL_TIMEOUT_MS` | OHPM 依赖安装 | 30 分钟 |
+| `EXPO_HARMONY_HVIGOR_BUILD_TIMEOUT_MS` | Hvigor 构建 | 15 分钟 |
+| `EXPO_HARMONY_EXPO_EXPORT_EMBED_TIMEOUT_MS` | `export:embed`（Hermes 打包） | 10 分钟 |
+| `EXPO_HARMONY_METRO_READY_TIMEOUT_MS` | 等待 Metro 就绪 | 30 分钟 |
+| `EXPO_HARMONY_START_EMULATOR_TIMEOUT_MS` | 等待模拟器连接 HDC | 2 分钟 |
+| `EXPO_HARMONY_INSTALL_HAP_TIMEOUT_MS` | 安装 HAP 到设备 | 2 分钟 |
+| `EXPO_HARMONY_LAUNCH_APP_TIMEOUT_MS` | 启动应用 | 30 秒 |
+| `EXPO_HARMONY_LIST_DEVICES_TIMEOUT_MS` | HDC 列出设备 | 15 秒 |
+| `EXPO_HARMONY_LIST_EMULATORS_TIMEOUT_MS` | 列出模拟器实例 | 15 秒 |
+| `EXPO_HARMONY_FORCE_STOP_APP_TIMEOUT_MS` | 强制停止应用 | 15 秒 |
+| `EXPO_HARMONY_LIST_METRO_PORTS_TIMEOUT_MS` | 列出 Metro 端口转发 | 15 秒 |
+| `EXPO_HARMONY_REMOVE_METRO_PORT_TIMEOUT_MS` | 移除 Metro 端口转发 | 15 秒 |
+| `EXPO_HARMONY_REVERSE_METRO_PORT_TIMEOUT_MS` | 反向转发 Metro 端口 | 15 秒 |
+| `EXPO_HARMONY_HDC_TIMEOUT_MS` | 其他 HDC 命令 | 60 秒 |
+| `EXPO_HARMONY_DOCTOR_TIMEOUT_MS` | Doctor 工具检查 | 10 秒 |
+
 ## Author
 
 **expo-harmony** © [Baoshuo](https://github.com/renbaoshuo), Released under the MIT License.<br>

package/build/doctor/doctor.js

@@ -13,6 +13,7 @@ const config_plugins_1 = require("@expo-harmony/config-plugins");
 const expo_modules_autolinking_1 = require("@expo-harmony/expo-modules-autolinking");
 const internal_1 = require("@expo-harmony/prebuild-config/internal");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 const projectLock_1 = require("../projectLock");
 const project_1 = require("../native/project");
 const toolchain_1 = require("../native/toolchain");
@@ -179,7 +180,7 @@ async function doctorUnlockedAsync(root, options = {}) {
                 capture: true,
                 cwd: root,
                 operation: `doctor-${id}`,
-                timeoutMs: 10_000,
+                timeoutMs: (0, timeout_1.resolveTimeoutMs)('doctor', 10_000),
             });
             checks.push(result.code === 0 && !result.timedOut
                 ? check(id, 'pass', `${command} is available through ${tool.source}.`)

package/build/exportEmbed/export.js

@@ -15,6 +15,7 @@ const errors_1 = require("../errors");
 const projectLock_1 = require("../projectLock");
 const project_1 = require("../native/project");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 const expo_1 = require("../expo");
 const manifest_1 = require("./manifest");
 async function exportEmbedUnlockedAsync(root, options = {}) {
@@ -63,7 +64,7 @@ async function exportEmbedUnlockedAsync(root, options = {}) {
             },
             operation: 'expo-export-embed',
             outputLimit: 4 * 1024 * 1024,
-            timeoutMs: options.timeoutMs || 10 * 60_000,
+            timeoutMs: (0, timeout_1.resolveTimeoutMs)('expo-export-embed', 10 * 60_000, options.timeoutMs),
         });
         if (result.code !== 0 || result.timedOut) {
             const diagnostics = (0, process_1.formatDiagnostics)(result);

package/build/native/build.js

@@ -15,6 +15,7 @@ const log_1 = require("../log");
 const path_1 = require("../path");
 const process_1 = require("../process");
 const profile_1 = require("../profile");
+const timeout_1 = require("../timeout");
 async function buildNativeAsync(root, plan, tools, options, steps) {
     let exported = null;
     const embedded = plan.buildMode === 'release' || (0, config_1.getConfig)(root).exp.updates?.useNativeDebug === true;
@@ -59,7 +60,7 @@ async function buildNativeAsync(root, plan, tools, options, steps) {
         },
         message: 'Hvigor build',
         operation: 'hvigor-build',
-        timeoutMs: 15 * 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('hvigor-build', 15 * 60_000),
     }));
     if (!(0, file_1.isNonEmptyRegularFile)(plan.expectedHap)) {
         throw new errors_1.HarmonyCliError('ERR_HARMONY_HAP_MISSING', 'Hvigor completed without producing the expected non-empty regular HAP.', { operation: 'verify-hap' });

package/build/native/install.js

@@ -2,12 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installHarmonyDependenciesAsync = installHarmonyDependenciesAsync;
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 async function installHarmonyDependenciesAsync(plan, tools, options = {}) {
     await (0, process_1.runCheckedAsync)(tools.ohpm.command, [...tools.ohpm.args, 'install', '--all'], {
         code: 'ERR_HARMONY_OHPM_FAILED',
         cwd: plan.harmonyRoot,
         message: 'OHPM install',
         operation: 'ohpm-install',
-        timeoutMs: options.timeoutMs || 5 * 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('ohpm-install', 30 * 60_000, options.timeoutMs),
     });
 }

package/build/run/devices.js

@@ -8,6 +8,7 @@ const promises_1 = require("node:timers/promises");
 const emulators_1 = require("./emulators");
 const errors_1 = require("../errors");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 function parseHdcTargets(output) {
     const trimmed = String(output).trim();
     if (!trimmed || trimmed === '[Empty]')
@@ -42,7 +43,7 @@ async function runHdcAsync(hdc, args, options = {}) {
         cwd: options.cwd,
         operation: options.operation || 'hdc',
         outputLimit: options.outputLimit || 256 * 1024,
-        timeoutMs: options.timeoutMs || 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)(options.operation || 'hdc', 60_000, options.timeoutMs),
     });
     if (!options.allowFailure && hasCommandFailure(result)) {
         const diagnostics = (0, process_1.formatDiagnostics)(result, 2_000);
@@ -56,7 +57,7 @@ async function listConnectedDevicesAsync(hdc, options) {
         cwd: options.cwd,
         message: 'Cannot list Harmony devices',
         operation: 'list-devices',
-        timeoutMs: options.timeoutMs || 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('list-devices', 15_000, options.timeoutMs),
     });
     const targets = parseHdcTargets(result.stdout || result.stderr);
     return targets.filter(target => target.state.toLowerCase() === 'connected');
@@ -110,7 +111,7 @@ async function selectDeviceAsync(hdc, requested, options = {}) {
         launch = (0, emulators_1.startEmulator)(options.emulator, instance.name, options.emulatorLogFile, options.cwd);
     }
     options.onProgress?.(`Waiting for Harmony emulator ${instance.name} to connect`);
-    const deadline = Date.now() + (options.timeoutMs || 120_000);
+    const deadline = Date.now() + (0, timeout_1.resolveTimeoutMs)('start-emulator', 120_000, options.timeoutMs);
     while (Date.now() < deadline) {
         launch?.assertRunning();
         const devices = await listConnectedDevicesAsync(hdc, {
@@ -155,7 +156,7 @@ async function installHapAsync(hdc, device, hap, options = {}) {
         cwd: options.cwd,
         message: `Cannot install the Harmony HAP on ${device.id}`,
         operation: 'install-hap',
-        timeoutMs: options.timeoutMs || 2 * 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('install-hap', 2 * 60_000, options.timeoutMs),
     });
 }
 async function configureMetroPortAsync(hdc, device, port, options = {}) {
@@ -171,7 +172,7 @@ async function configureMetroPortAsync(hdc, device, port, options = {}) {
     const forwards = await runHdcAsync(hdc, ['-t', device.id, 'fport', 'ls'], {
         cwd: options.cwd,
         operation: 'list-metro-ports',
-        timeoutMs: 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('list-metro-ports', 15_000, options.timeoutMs),
     });
     for (const line of forwards.stdout.split(/\r?\n/u)) {
         const [target, remote, local, direction] = line.trim().split(/\s+/u);
@@ -182,7 +183,7 @@ async function configureMetroPortAsync(hdc, device, port, options = {}) {
         await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', remote, local], {
             cwd: options.cwd,
             operation: 'remove-metro-port',
-            timeoutMs: 15_000,
+            timeoutMs: (0, timeout_1.resolveTimeoutMs)('remove-metro-port', 15_000, options.timeoutMs),
         });
     }
     await runHdcAsync(hdc, ['-t', device.id, 'rport', deviceEndpoint, hostEndpoint], {
@@ -190,7 +191,7 @@ async function configureMetroPortAsync(hdc, device, port, options = {}) {
         cwd: options.cwd,
         message: `Cannot reverse Metro port ${port} for ${device.id}`,
         operation: 'reverse-metro-port',
-        timeoutMs: 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('reverse-metro-port', 15_000, options.timeoutMs),
     });
 }
 async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}) {
@@ -204,7 +205,7 @@ async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}
         allowFailure: true,
         cwd: options.cwd,
         operation: 'force-stop-app',
-        timeoutMs: 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('force-stop-app', 15_000),
     });
     await runHdcAsync(hdc, [
         '-t', device.id,
@@ -218,6 +219,6 @@ async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}
         cwd: options.cwd,
         message: `Cannot launch ${bundleName} on ${device.id}`,
         operation: 'launch-app',
-        timeoutMs: 30_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('launch-app', 30_000),
     });
 }

package/build/run/emulators.js

@@ -10,6 +10,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const errors_1 = require("../errors");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 async function listEmulatorsAsync(tool, options = {}) {
     let result;
     try {
@@ -17,7 +18,7 @@ async function listEmulatorsAsync(tool, options = {}) {
             capture: true,
             cwd: options.cwd,
             operation: 'list-emulators',
-            timeoutMs: options.timeoutMs || 15_000,
+            timeoutMs: (0, timeout_1.resolveTimeoutMs)('list-emulators', 15_000, options.timeoutMs),
         });
     }
     catch (cause) {

package/build/run/metro.js

@@ -10,6 +10,7 @@ const session_1 = require("../development/session");
 const errors_1 = require("../errors");
 const process_1 = require("../process");
 const expo_1 = require("../expo");
+const timeout_1 = require("../timeout");
 function delay(milliseconds) {
     return new Promise(resolve => setTimeout(resolve, milliseconds));
 }
@@ -107,7 +108,7 @@ async function startExpoMetroAsync(projectRoot, options) {
         exitError = error;
     });
     const startedAt = Date.now();
-    const timeoutMs = options.readyTimeoutMs || 1800000;
+    const timeoutMs = (0, timeout_1.resolveTimeoutMs)('metro-ready', 30 * 60_000, options.readyTimeoutMs);
     try {
         while (Date.now() - startedAt < timeoutMs) {
             if (exitError instanceof errors_1.HarmonyCliError) {

package/build/timeout.d.ts

@@ -0,0 +1,8 @@
+declare function timeoutEnvName(operation: string): string;
+/**
+ * Resolves a command timeout: explicit option first, then the
+ * `EXPO_HARMONY_<OPERATION>_TIMEOUT_MS` environment variable derived from the
+ * operation name (dashes become underscores), then the built-in default.
+ */
+declare function resolveTimeoutMs(operation: string, fallbackMs: number, explicitMs?: number): number;
+export { resolveTimeoutMs, timeoutEnvName };

package/build/timeout.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTimeoutMs = resolveTimeoutMs;
+exports.timeoutEnvName = timeoutEnvName;
+const TimeoutEnvPrefix = 'EXPO_HARMONY_';
+const warnedEnvNames = new Set();
+function timeoutEnvName(operation) {
+    return `${TimeoutEnvPrefix}${operation.toUpperCase().replace(/-/gu, '_')}_TIMEOUT_MS`;
+}
+function timeoutFromEnv(operation) {
+    const name = timeoutEnvName(operation);
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0)
+        return parsed;
+    if (!warnedEnvNames.has(name)) {
+        warnedEnvNames.add(name);
+        console.warn(`Ignoring unsupported ${name} value: ${raw}. Use a positive number of milliseconds.`);
+    }
+    return null;
+}
+/**
+ * Resolves a command timeout: explicit option first, then the
+ * `EXPO_HARMONY_<OPERATION>_TIMEOUT_MS` environment variable derived from the
+ * operation name (dashes become underscores), then the built-in default.
+ */
+function resolveTimeoutMs(operation, fallbackMs, explicitMs) {
+    return explicitMs && explicitMs > 0
+        ? explicitMs
+        : timeoutFromEnv(operation) ?? fallbackMs;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo-harmony/cli",
-  "version": "55.0.26-harmony.11",
+  "version": "55.0.26-harmony.12",
   "keywords": [
     "react-native",
     "expo",

package/src/doctor/doctor.ts

@@ -8,6 +8,7 @@ import { verifyModulesAsync } from '@expo-harmony/expo-modules-autolinking';
 import { isRnohAutolinkingDisabled, validateHarmonySigningConfigFile } from '@expo-harmony/prebuild-config/internal';
 
 import { spawnAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 import { withHarmonyProjectLockAsync } from '../projectLock';
 import { resolveHarmonyBuildPlanIfPresentAsync } from '../native/project';
 import { resolveHarmonyToolchain, type HarmonyTool } from '../native/toolchain';
@@ -221,7 +222,7 @@ async function doctorUnlockedAsync(root: string, options: DoctorOptions = {}): P
         capture: true,
         cwd: root,
         operation: `doctor-${id}`,
-        timeoutMs: 10_000,
+        timeoutMs: resolveTimeoutMs('doctor', 10_000),
       });
 
       checks.push(result.code === 0 && !result.timedOut

package/src/exportEmbed/export.ts

@@ -10,6 +10,7 @@ import { HarmonyCliError } from '../errors';
 import { withHarmonyProjectLockAsync } from '../projectLock';
 import { resolveHarmonyBuildPlanAsync } from '../native/project';
 import { formatDiagnostics, spawnAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 import { resolveExpoHermesBuilder } from '../expo';
 import {
   assertHermesBundle, assertSourceMap, exportPaths,
@@ -88,7 +89,7 @@ async function exportEmbedUnlockedAsync(
       },
       operation: 'expo-export-embed',
       outputLimit: 4 * 1024 * 1024,
-      timeoutMs: options.timeoutMs || 10 * 60_000,
+      timeoutMs: resolveTimeoutMs('expo-export-embed', 10 * 60_000, options.timeoutMs),
     });
 
     if (result.code !== 0 || result.timedOut) {

package/src/native/build.ts

@@ -12,6 +12,7 @@ import { progress, type Log } from '../log';
 import { toPosixPath } from '../path';
 import { runCheckedAsync } from '../process';
 import { timedAsync } from '../profile';
+import { resolveTimeoutMs } from '../timeout';
 
 export interface NativeBuildResult {
   export: null | { assetCount: number; bundleSha256: string; sourceMapSha256: string };
@@ -70,7 +71,7 @@ export async function buildNativeAsync(
     },
     message: 'Hvigor build',
     operation: 'hvigor-build',
-    timeoutMs: 15 * 60_000,
+    timeoutMs: resolveTimeoutMs('hvigor-build', 15 * 60_000),
   }));
 
   if (!isNonEmptyRegularFile(plan.expectedHap)) {

package/src/native/install.ts

@@ -1,6 +1,7 @@
 import type { HarmonyBuildPlan } from './types';
 import type { HarmonyToolchain } from './toolchain';
 import { runCheckedAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 
 export async function installHarmonyDependenciesAsync(
   plan: Pick<HarmonyBuildPlan, 'harmonyRoot'>,
@@ -12,6 +13,6 @@ export async function installHarmonyDependenciesAsync(
     cwd: plan.harmonyRoot,
     message: 'OHPM install',
     operation: 'ohpm-install',
-    timeoutMs: options.timeoutMs || 5 * 60_000,
+    timeoutMs: resolveTimeoutMs('ohpm-install', 30 * 60_000, options.timeoutMs),
   });
 }

package/src/run/devices.ts

@@ -4,6 +4,7 @@ import { listEmulatorsAsync, startEmulator } from './emulators';
 import { HarmonyCliError } from '../errors';
 import { type HarmonyTool } from '../native/toolchain';
 import { formatDiagnostics, spawnAsync, type ProcessResult } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 
 interface Device {
   aliases: string[];
@@ -74,7 +75,7 @@ async function runHdcAsync(
     cwd: options.cwd,
     operation: options.operation || 'hdc',
     outputLimit: options.outputLimit || 256 * 1024,
-    timeoutMs: options.timeoutMs || 60_000,
+    timeoutMs: resolveTimeoutMs(options.operation || 'hdc', 60_000, options.timeoutMs),
   });
 
   if (!options.allowFailure && hasCommandFailure(result)) {
@@ -95,7 +96,7 @@ async function listConnectedDevicesAsync(hdc: HarmonyTool, options: HdcOptions):
     cwd: options.cwd,
     message: 'Cannot list Harmony devices',
     operation: 'list-devices',
-    timeoutMs: options.timeoutMs || 15_000,
+    timeoutMs: resolveTimeoutMs('list-devices', 15_000, options.timeoutMs),
   });
   const targets = parseHdcTargets(result.stdout || result.stderr);
   return targets.filter(target => target.state.toLowerCase() === 'connected');
@@ -173,7 +174,7 @@ async function selectDeviceAsync(
   }
 
   options.onProgress?.(`Waiting for Harmony emulator ${instance.name} to connect`);
-  const deadline = Date.now() + (options.timeoutMs || 120_000);
+  const deadline = Date.now() + resolveTimeoutMs('start-emulator', 120_000, options.timeoutMs);
   while (Date.now() < deadline) {
     launch?.assertRunning();
     const devices = await listConnectedDevicesAsync(hdc, {
@@ -223,7 +224,7 @@ async function installHapAsync(
     cwd: options.cwd,
     message: `Cannot install the Harmony HAP on ${device.id}`,
     operation: 'install-hap',
-    timeoutMs: options.timeoutMs || 2 * 60_000,
+    timeoutMs: resolveTimeoutMs('install-hap', 2 * 60_000, options.timeoutMs),
   });
 }
 
@@ -247,7 +248,7 @@ async function configureMetroPortAsync(
   const forwards = await runHdcAsync(hdc, ['-t', device.id, 'fport', 'ls'], {
     cwd: options.cwd,
     operation: 'list-metro-ports',
-    timeoutMs: 15_000,
+    timeoutMs: resolveTimeoutMs('list-metro-ports', 15_000, options.timeoutMs),
   });
 
   for (const line of forwards.stdout.split(/\r?\n/u)) {
@@ -258,7 +259,7 @@ async function configureMetroPortAsync(
     await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', remote, local], {
       cwd: options.cwd,
       operation: 'remove-metro-port',
-      timeoutMs: 15_000,
+      timeoutMs: resolveTimeoutMs('remove-metro-port', 15_000, options.timeoutMs),
     });
   }
 
@@ -267,7 +268,7 @@ async function configureMetroPortAsync(
     cwd: options.cwd,
     message: `Cannot reverse Metro port ${port} for ${device.id}`,
     operation: 'reverse-metro-port',
-    timeoutMs: 15_000,
+    timeoutMs: resolveTimeoutMs('reverse-metro-port', 15_000, options.timeoutMs),
   });
 }
 
@@ -288,7 +289,7 @@ async function launchAppAsync(
     allowFailure: true,
     cwd: options.cwd,
     operation: 'force-stop-app',
-    timeoutMs: 15_000,
+    timeoutMs: resolveTimeoutMs('force-stop-app', 15_000),
   });
 
   await runHdcAsync(hdc, [
@@ -303,7 +304,7 @@ async function launchAppAsync(
     cwd: options.cwd,
     message: `Cannot launch ${bundleName} on ${device.id}`,
     operation: 'launch-app',
-    timeoutMs: 30_000,
+    timeoutMs: resolveTimeoutMs('launch-app', 30_000),
   });
 }
 

package/src/run/emulators.ts

@@ -4,6 +4,7 @@ import spawn from 'cross-spawn';
 
 import { HarmonyCliError } from '../errors';
 import { formatDiagnostics, spawnAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 import { type HarmonyTool } from '../native/toolchain';
 
 interface HarmonyEmulator {
@@ -21,7 +22,7 @@ async function listEmulatorsAsync(
       capture: true,
       cwd: options.cwd,
       operation: 'list-emulators',
-      timeoutMs: options.timeoutMs || 15_000,
+      timeoutMs: resolveTimeoutMs('list-emulators', 15_000, options.timeoutMs),
     });
   } catch (cause) {
     throw new HarmonyCliError(

package/src/run/metro.ts

@@ -4,6 +4,7 @@ import { readDevelopmentSessionAsync } from '../development/session';
 import { HarmonyCliError } from '../errors';
 import { formatDiagnostics, startManagedProcess, type ProcessResult } from '../process';
 import { resolveExpoCli } from '../expo';
+import { resolveTimeoutMs } from '../timeout';
 
 type MetroStatus = 'free' | 'metro' | 'occupied';
 
@@ -155,7 +156,7 @@ async function startExpoMetroAsync(
   );
 
   const startedAt = Date.now();
-  const timeoutMs = options.readyTimeoutMs || 1800000;
+  const timeoutMs = resolveTimeoutMs('metro-ready', 30 * 60_000, options.readyTimeoutMs);
 
   try {
     while (Date.now() - startedAt < timeoutMs) {

package/src/timeout.ts

@@ -0,0 +1,35 @@
+const TimeoutEnvPrefix = 'EXPO_HARMONY_';
+
+const warnedEnvNames = new Set<string>();
+
+function timeoutEnvName(operation: string): string {
+  return `${TimeoutEnvPrefix}${operation.toUpperCase().replace(/-/gu, '_')}_TIMEOUT_MS`;
+}
+
+function timeoutFromEnv(operation: string): number | null {
+  const name = timeoutEnvName(operation);
+  const raw = process.env[name];
+  if (!raw) return null;
+
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+
+  if (!warnedEnvNames.has(name)) {
+    warnedEnvNames.add(name);
+    console.warn(`Ignoring unsupported ${name} value: ${raw}. Use a positive number of milliseconds.`);
+  }
+  return null;
+}
+
+/**
+ * Resolves a command timeout: explicit option first, then the
+ * `EXPO_HARMONY_<OPERATION>_TIMEOUT_MS` environment variable derived from the
+ * operation name (dashes become underscores), then the built-in default.
+ */
+function resolveTimeoutMs(operation: string, fallbackMs: number, explicitMs?: number): number {
+  return explicitMs && explicitMs > 0
+    ? explicitMs
+    : timeoutFromEnv(operation) ?? fallbackMs;
+}
+
+export { resolveTimeoutMs, timeoutEnvName };