@expo-harmony/cli 55.0.26-harmony.5 → 55.0.26-harmony.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +45 -26
  2. package/build/buildHap/common.d.ts +1 -1
  3. package/build/run/run.js +4 -1
  4. package/package.json +2 -2
  5. package/src/buildHap/common.ts +1 -1
  6. package/src/run/run.ts +4 -1
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/cli)
4
4
 
5
- 为 Expo 项目提供 HarmonyOS 平台的命令行工具，支持 Metro 开发服务、CNG 原生工程生成、环境诊断、Harmony Expo Module 发现与校验、生产 Bundle 导出，以及 HAP 的构建、安装和启动。
5
+ Expo 项目的 HarmonyOS 命令行工具：启动 Metro 开发服务、生成原生工程、构建和安装 HAP。
6
6
 
7
7
  ## 安装
8
8
 
@@ -10,11 +10,11 @@
10
10
  npm install --save-dev @expo-harmony/cli
11
11
  ```
12
12
 
13
- CLI 必须安装在项目本地，JS 打包调用项目内的 Expo CLI，Hermes 字节码编译调用项目内的 `@expo/metro-config`，Release 原生构建也会回调项目本地的 `expo-harmony` 二进制生成 Bundle。
13
+ CLI 必须装在项目本地。JS 打包调用项目内的 Expo CLI，Hermes 字节码编译调用项目内的 `@expo/metro-config`，Release 原生构建回调项目本地的 `expo-harmony` 二进制生成 Bundle。
14
14
 
15
- 项目需要 Node.js 20 或更高版本，在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件，并使用 `@expo-harmony/metro-config` 组合 Metro 配置。
15
+ 项目需要 Node.js 20 或更高版本，在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件，并用 `@expo-harmony/metro-config` 组合 Metro 配置。
16
16
 
17
- HAP 构建需要完整的 HarmonyOS SDK（含 HMS 与 OpenHarmony 组件）、OHPM、Hvigor 和 HDC，这些环境可用 `doctor` 命令检查。
17
+ HAP 构建需要完整的 HarmonyOS SDK（含 HMS 和 OpenHarmony 组件）、OHPM、Hvigor 和 HDC。用 `doctor` 检查这些环境。
18
18
 
19
19
  ## 命令
20
20
 
@@ -32,7 +32,7 @@ HAP 构建需要完整的 HarmonyOS SDK（含 HMS 与 OpenHarmony 组件）、OH
32
32
  | `expo-harmony export:embed` | 导出 Hermes 字节码、资源和 Source Map 并写入原生工程 |
33
33
  | `expo-harmony run` | 构建 HAP，在连接的 HarmonyOS 设备上安装并启动应用 |
34
34
 
35
- 所有命令都可接收可选的项目路径（`modules` 命令写在子命令之后）；未提供时从当前目录向上查找最近的项目根目录作为默认值：
35
+ 所有命令都可以带一个可选的项目路径；`modules` 的路径写在子命令后面。不提供时，从当前目录向上找最近的项目根目录：
36
36
 
37
37
  ```sh
38
38
  npx expo-harmony start ./my-app
@@ -50,13 +50,13 @@ npx expo-harmony start --port 8082
50
50
  npx expo-harmony start --clear
51
51
  ```
52
52
 
53
- 所有命令都会在 CLI 入口、读取应用配置之前设置 `EXPO_HARMONY=1` 和 `EXPO_METRO_TARGET=harmony`。
53
+ CLI 入口先设置 `EXPO_HARMONY=1` 和 `EXPO_METRO_TARGET=harmony`，再读取应用配置，所有命令都如此。
54
54
 
55
- `start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro。它只启动 JS 开发服务，不执行原生工程生成、构建、安装、应用启动或设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。新启动的 Metro 在当前终端输出日志，按 Ctrl+C 退出。
55
+ `start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro。它只启动 JS 开发服务：不生成原生工程，不构建、安装、启动应用，不做设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。Metro 在当前终端输出日志，Ctrl+C 退出。
56
56
 
57
- 支持 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；此时缓存选项不会生效，需要先停止已有 Metro 后重新执行命令。端口被其他进程占用时会报错。
57
+ 选项有 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；这时缓存选项不生效，要先停掉已有的 Metro 再执行一次。端口被其他进程占用时报错。
58
58
 
59
- 需要构建并启动应用时，在另一个终端运行 `expo-harmony run --no-bundler`；若指定了端口，两个命令使用相同的 `--port`。
59
+ 要构建并启动应用，在另一个终端运行 `expo-harmony run --no-bundler`；指定了端口时，两个命令用同一个 `--port`。
60
60
 
61
61
  ## Prebuild
62
62
 
@@ -66,9 +66,11 @@ npx expo-harmony prebuild --clean
66
66
  npx expo-harmony prebuild --check
67
67
  ```
68
68
 
69
- `prebuild` 固定使用 HarmonyOS 平台和 `@expo-harmony/template` 模板，因此不像官方接受 `--platform` 和 `--template`。依赖安装相关选项会透传给 Expo CLI：`--no-install`、`--npm`/`--yarn`/`--pnpm`/`--bun`（最多选择一个）和 `--skip-dependency-update <packages>`。执行前会先运行一次 doctor（此阶段不要求构建工具就绪），发现阻塞错误时直接中止。
69
+ `prebuild` 固定生成 HarmonyOS 平台，固定用 `@expo-harmony/template` 模板，因此没有 `--platform` 和 `--template`。依赖安装的选项透传给 Expo CLI：`--no-install`、`--npm`/`--yarn`/`--pnpm`/`--bun`（最多选一个）和 `--skip-dependency-update <packages>`。执行前先跑一遍 doctor，有阻塞错误就中止；这个阶段不要求构建工具就绪。
70
70
 
71
- `--clean` 只会清理带有 Expo Harmony 模板标记的原生目录：CNG manifest 缺失、目标不是项目内的普通目录或模板标记异常时都会拒绝删除。`--check` 是只读操作，会把项目镜像到临时目录（`node_modules` 中的包目录通过链接共享，Windows 下的普通文件复制到临时目录，无须文件符号链接权限），在其中执行一次隔离的 prebuild 后比较受管文件；无差异时退出码为 `0`，有差异时列出变更并以 `2` 退出，且不能与其他会修改工程的选项同时使用。
71
+ `--clean` 只删除带 Expo Harmony 模板标记的原生目录。CNG manifest 缺失、目标不是项目内的普通目录、模板标记异常，都拒绝删除。
72
+
73
+ `--check` 是只读操作。它把项目镜像到临时目录（`node_modules` 里的包目录用链接共享，Windows 下的普通文件复制过去，不需要文件符号链接权限），在临时目录里执行一次 prebuild，再比较受管文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能和其他会修改工程的选项一起用。
72
74
 
73
75
  ## Build
74
76
 
@@ -78,9 +80,9 @@ npx expo-harmony build --variant release
78
80
  npx expo-harmony build --sync
79
81
  ```
80
82
 
81
- `build` 在不使用设备的前提下完成 HAP 构建。缺少原生工程时自动执行 prebuild，`--sync` 强制重新生成，默认则校验 CNG 期望状态并在发现差错时报错。随后依次执行 OHPM 依赖安装、原生构建缓存校验和 Hvigor `assembleHap`，最后确认产物 HAP 存在且非空。原生依赖指纹变化时会自动失效旧的 `.cxx` 和 `build` 缓存，避免链接到过期的产物。
83
+ `build` 构建 HAP，不选设备，也不安装和启动应用。没有原生工程时先执行 prebuild；`--sync` 强制重新生成；默认只校验 CNG 期望状态，发现差错就报错。之后安装 OHPM 依赖、校验原生构建缓存、执行 Hvigor `assembleHap`，最后确认产物 HAP 存在且非空。原生依赖的指纹变化时，旧的 `.cxx` 和 `build` 缓存会失效，不会链接到过期产物。
82
84
 
83
- 选项：`--variant debug|release`（默认 `debug`）和 `--sync`。Release 构建会先执行生产导出，再带着预生成的 Bundle 进入 Hvigor。
85
+ 选项：`--variant debug|release`（默认 `debug`）和 `--sync`。Release 构建先执行生产导出，再带着预生成的 Bundle 进 Hvigor。
84
86
 
85
87
  ## Doctor
86
88
 
@@ -88,7 +90,18 @@ npx expo-harmony build --sync
88
90
  npx expo-harmony doctor
89
91
  ```
90
92
 
91
- `doctor` 逐项检查 Expo `harmony` 配置与 `@expo-harmony/prebuild-config` 插件注册、签名配置文件、启用 Harmony 的 Metro 配置、必需依赖（RNOH 运行时与 CLI、`@expo-harmony/expo-modules-autolinking`）、Harmony Expo Modules 校验、完整的 HarmonyOS SDK、HDC/OHPM/Hvigor 可用性，以及生成工程中的 Hvigor 文件和 RNOH 自动链接禁用状态。存在 error 级别的问题时命令以非零状态退出；未配置外部签名文件只会警告，不影响未签名构建。
93
+ `doctor` 逐项检查：
94
+
95
+ - Expo `harmony` 配置和 `@expo-harmony/prebuild-config` 插件注册
96
+ - 签名配置文件
97
+ - Metro 配置是否启用 Harmony
98
+ - 必需依赖：RNOH 运行时和 CLI、`@expo-harmony/expo-modules-autolinking`
99
+ - Harmony Expo Modules
100
+ - HarmonyOS SDK 是否完整
101
+ - HDC、OHPM、Hvigor 是否可用
102
+ - 生成工程中的 Hvigor 文件和 RNOH 自动链接禁用状态
103
+
104
+ 有 error 级别的问题时，命令以非零状态退出。未配置外部签名文件只警告，不影响未签名构建。
92
105
 
93
106
  ## Modules
94
107
 
@@ -98,7 +111,7 @@ npx expo-harmony modules inspect --package expo-linear-gradient
98
111
  npx expo-harmony modules verify
99
112
  ```
100
113
 
101
- `list` 列出发现的模块候选（包名、版本、来源），并标出不支持 Harmony 的模块、重复版本和缺失的必需依赖。`inspect` 展示模块解析后的完整元数据，包括包根、ArkTS modules 和 HAR 路径，`--package <name>` 可筛选单个模块，未发现时报错。`verify` 输出诊断信息，存在 error 时以非零状态退出。
114
+ `list` 列出发现的模块候选（包名、版本、来源），标出不支持 Harmony 的模块、重复版本和缺失的必需依赖。`inspect` 展示模块解析后的元数据：包根、ArkTS modules、HAR 路径。`--package <name>` 筛选单个模块，未发现时报错。`verify` 输出诊断信息，有 error 时以非零状态退出。
102
115
 
103
116
  三个子命令都支持 `--variant debug|release` 和 `--native-modules-dir <dir>`（app-local 模块目录，默认 `./modules`）。
104
117
 
@@ -110,7 +123,11 @@ npx expo-harmony export:embed --check
110
123
  npx expo-harmony export:embed --reset-cache
111
124
  ```
112
125
 
113
- `export:embed` 先运行 doctor，再用项目本地的 Expo CLI 生成 Harmony 平台的 JS Bundle 和资源，并交给项目本地 `@expo/metro-config` 的 Hermes 导出器编译字节码、合并 Source Map。产物经过校验（Hermes 字节码魔数、Source Map 不含宿主机绝对路径）后原子写入原生工程：Bundle 和资源进入模块的 `rawfile` 目录，Source Map 与清单写入 `.expo/harmony/export/`。清单 `.expo/harmony/export-manifest.json` 记录每个文件的哈希与大小，`--check` 据此校验已有导出而不重新构建，`--reset-cache` 会透传给 Metro 清除转换缓存。
126
+ `export:embed` 先运行 doctor，再用项目本地的 Expo CLI 生成 Harmony 平台的 JS Bundle 和资源，交给项目本地的 `@expo/metro-config` 的 Hermes 导出器编译字节码、合并 Source Map。
127
+
128
+ 产物先校验再写入：检查 Hermes 字节码魔数、Source Map 不含宿主机绝对路径，然后原子写入原生工程。Bundle 和资源进入模块的 `rawfile` 目录，Source Map 和清单写入 `.expo/harmony/export/`。
129
+
130
+ 清单 `.expo/harmony/export-manifest.json` 记录每个文件的哈希和大小。`--check` 按清单校验已有的导出，不重新构建。`--reset-cache` 透传给 Metro，清除转换缓存。
114
131
 
115
132
  ## Run
116
133
 
@@ -121,28 +138,30 @@ npx expo-harmony run \
121
138
  --port 8081
122
139
  ```
123
140
 
124
- `run` 会依次执行环境诊断、确保原生工程（缺失时自动预构建，`--sync` 强制重新生成，否则校验 CNG 状态）、选择设备、Release 生产导出、OHPM 安装、Hvigor 构建、Metro 端口反向映射（仅 Debug）、HAP 安装和 Ability 启动。模块接线的最终正确性由 OHPM、Hvigor、CMake 和 ArkTS 编译器验证。
141
+ `run` 按顺序执行：环境诊断、确保原生工程（缺失时预构建，`--sync` 强制重新生成，否则复用已有工程）、选择设备、Release 生产导出、OHPM 安装、Hvigor 构建、Metro 端口反向映射（仅 Debug）、HAP 安装、Ability 启动。模块接线是否正确，由 OHPM、Hvigor、CMake 和 ArkTS 编译器验证。
125
142
 
126
143
  常用选项：
127
144
 
128
- - `--variant debug|release`：选择构建模式，默认为 `debug`。Release 构建会先执行生产导出，不启动 Metro。
129
- - `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。存在多个候选目标时必须指定。
130
- - `--port <number>`：设置 Metro 端口及设备反向映射端口，默认为 `8081`。
131
- - `--no-bundler`：连接已经运行的 Expo Metro，不启动新的服务；端口空闲或被其他进程占用时会报错。不加此选项时，若端口上已有 Metro 在运行则直接复用。
145
+ - `--variant debug|release`：构建模式，默认 `debug`。Release 先执行生产导出，不启动 Metro。
146
+ - `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。有多个候选目标时必须指定。
147
+ - `--port <number>`：Metro 端口和设备反向映射端口，默认 `8081`。
148
+ - `--no-bundler`：连接已经在运行的 Expo Metro，不启动新的服务；端口空闲或被其他进程占用时报错。不加此选项时，端口上已有 Metro 在运行就直接复用。
132
149
  - `--reset-cache`：Debug 模式下启动 Metro 时清除 Metro 缓存；Release 模式下清除生产导出缓存。
133
150
  - `--no-install`：跳过 HAP 安装，直接启动设备上已有的应用。
134
- - `--app-id <bundleName>`：指定要启动的应用；与生成包名不同时必须同时使用 `--no-install`。
151
+ - `--app-id <bundleName>`：指定要启动的应用；与生成的包名不同时，必须同时使用 `--no-install`。
135
152
  - `--sync`：构建前强制重新执行一次预构建。
136
153
 
137
- Debug 模式下由 CLI 启动的 Metro 会接管终端输出日志，按 Ctrl+C 退出。
154
+ Debug 模式下由 CLI 启动的 Metro 接管终端输出日志，Ctrl+C 退出。
138
155
 
139
- 未指定 `--device` 时，优先使用已连接的设备；没有连接的设备时，优先等待正在启动的模拟器，否则自动启动唯一的本地模拟器。存在多个候选模拟器时会列出名称，使用 `--device "模拟器名称"` 选择。通过模拟器名称选择或自动拉起时，等待 HDC 连接并确认该实例开机完成后才继续构建、安装和启动应用，最多等待 120 秒；退出 CLI 或 Metro 后模拟器继续运行。
156
+ 未指定 `--device` 时，优先用已连接的设备。没有连接的设备时，先等正在启动的模拟器；否则启动唯一的本地模拟器。有多个候选模拟器时列出名称，用 `--device "模拟器名称"` 选择。通过名称选择或自动拉起模拟器时，CLI 等 HDC 连接、确认开机完成后才继续构建、安装和启动，最多等 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
140
157
 
141
- 自动启动需要 DevEco Studio 6.1.0 或更新版本，并已在 Device Manager 中创建模拟器。CLI 按[华为模拟器命令行文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-emulator-command-line)调用 `Emulator -list -details` 和 `Emulator -start <name>`，使用 DevEco Studio 配置的实例和镜像路径。启动日志保存在项目的 `.expo/harmony/emulator.log`。若启动失败，请先在 DevEco Studio 中处理首次使用协议或登录要求；文档注明需要登录开发者账号的模拟器版本无法通过命令行启动。
158
+ 自动启动需要 DevEco Studio 6.1.0 或更新版本，并且已在 Device Manager 中创建模拟器。CLI 按[华为模拟器命令行文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-emulator-command-line)调用 `Emulator -list -details` 和 `Emulator -start <name>`，使用 DevEco Studio 配置的实例和镜像路径。启动日志在项目的 `.expo/harmony/emulator.log`。启动失败时，先在 DevEco Studio 里处理首次使用协议或登录要求；文档注明需要登录开发者账号的模拟器版本无法从命令行启动。
142
159
 
143
160
  ## 工具链与环境变量
144
161
 
145
- 工具链按「环境变量覆盖 → DevEco Studio 安装布局 → PATH」的顺序解析。`HARMONY_HDC`、`HARMONY_EMULATOR`、`HARMONY_OHPM`、`HARMONY_HVIGORW` 和 `HARMONY_NODE` 可覆盖对应工具的路径，SDK 根目录可通过 `DEVECO_SDK_HOME`、`HARMONY_HOME` 或 `OHOS_SDK_HOME` 指定。Emulator 同时支持 DevEco Studio 的 `tools/emulator` 和 Command Line Tools 的 `emulator` 布局，仅在需要模拟器时调用。原生构建回调 CLI 时使用的 Node.js 可通过 `EXPO_HARMONY_NODE` 显式指定。
162
+ 工具链按「环境变量覆盖 → DevEco Studio 安装布局 → PATH」的顺序解析。
163
+
164
+ `HARMONY_HDC`、`HARMONY_EMULATOR`、`HARMONY_OHPM`、`HARMONY_HVIGORW` 和 `HARMONY_NODE` 覆盖对应工具的路径。SDK 根目录用 `DEVECO_SDK_HOME`、`HARMONY_HOME` 或 `OHOS_SDK_HOME` 指定。Emulator 支持 DevEco Studio 的 `tools/emulator` 和 Command Line Tools 的 `emulator` 两种布局，只在需要模拟器时调用。原生构建回调 CLI 时用的 Node.js 可以用 `EXPO_HARMONY_NODE` 指定。
146
165
 
147
166
  ## Author
148
167
 
package/build/buildHap/common.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  interface HarmonyBuildPipelineOptions {
2
2
  io?: Pick<Console, 'error' | 'log' | 'warn'>;
3
3
  requireDeviceTools?: boolean;
4
- /** @internal The caller already completed an isolated prebuild check. */
4
+ /** @internal Reuse the native project without an isolated drift check. */
5
5
  skipGeneratedProjectCheck?: boolean;
6
6
  sync: boolean;
7
7
  variant: 'debug' | 'release';
package/build/run/run.js CHANGED
@@ -43,7 +43,10 @@ async function runHarmonyUnlockedAsync(projectRoot, options = {}) {
43
43
  variant: options.variant || 'debug',
44
44
  };
45
45
  const steps = {};
46
- await (0, common_1.ensureGeneratedProjectAsync)(projectRoot, normalizedOptions, steps);
46
+ await (0, common_1.ensureGeneratedProjectAsync)(projectRoot, {
47
+ ...normalizedOptions,
48
+ skipGeneratedProjectCheck: true,
49
+ }, steps);
47
50
  const plan = await (0, common_1.timed)(steps, 'buildPlan', () => (0, tools_1.resolveHarmonyBuildPlanAsync)(projectRoot, { buildMode: normalizedOptions.variant }));
48
51
  const identity = resolveRunIdentity(plan, normalizedOptions);
49
52
  const toolchain = (0, tools_1.resolveHarmonyToolchain)();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expo-harmony/cli",
3
- "version": "55.0.26-harmony.5",
3
+ "version": "55.0.26-harmony.6",
4
4
  "keywords": [
5
5
  "react-native",
6
6
  "expo",
@@ -38,7 +38,7 @@
38
38
  "dependencies": {
39
39
  "@expo-harmony/config-plugins": "55.0.10-harmony.2",
40
40
  "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.3",
41
- "@expo-harmony/prebuild-config": "55.0.0-harmony.4",
41
+ "@expo-harmony/prebuild-config": "55.0.0-harmony.5",
42
42
  "@expo/config": "55.0.17",
43
43
  "cross-spawn": "^7.0.6",
44
44
  "json5": "2.2.3"
package/src/buildHap/common.ts CHANGED
@@ -10,7 +10,7 @@ import { resolveHarmonyBuildPlanIfPresentAsync } from '../tools';
10
10
  interface HarmonyBuildPipelineOptions {
11
11
  io?: Pick<Console, 'error' | 'log' | 'warn'>;
12
12
  requireDeviceTools?: boolean;
13
- /** @internal The caller already completed an isolated prebuild check. */
13
+ /** @internal Reuse the native project without an isolated drift check. */
14
14
  skipGeneratedProjectCheck?: boolean;
15
15
  sync: boolean;
16
16
  variant: 'debug' | 'release';
package/src/run/run.ts CHANGED
@@ -118,7 +118,10 @@ async function runHarmonyUnlockedAsync(
118
118
  };
119
119
  const steps: Record<string, number> = {};
120
120
 
121
- await ensureGeneratedProjectAsync(projectRoot, normalizedOptions, steps);
121
+ await ensureGeneratedProjectAsync(projectRoot, {
122
+ ...normalizedOptions,
123
+ skipGeneratedProjectCheck: true,
124
+ }, steps);
122
125
 
123
126
  const plan = await timed(steps, 'buildPlan', () => resolveHarmonyBuildPlanAsync(
124
127
  projectRoot,