expo-harmony

让 Expo（React Native）应用在 HarmonyOS / OpenHarmony 上运行的一体化 CLI 工具链与 CNG 基线。 同一套业务代码覆盖 iOS / Android / HarmonyOS 三端；Expo SDK 55 与 RNOH 0.84 双 React 共存， 全程沿用 Expo CNG（配置驱动、可随时重建）工作流。

AtomGit OH-Expo · 使用指南 · 支持矩阵 · 架构说明 · 能力看板

项目定位

让 Expo（React Native）应用在 HarmonyOS / OpenHarmony 上运行的一体化 CLI 工具链与 CNG 基线：

• 三端一套码：同一套业务代码覆盖 iOS / Android / HarmonyOS，平台差异走 Platform.OS === 'harmony' 与 .harmony.tsx/.harmony.ts 后缀；
• CNG 配置驱动：app.json 是唯一真相源，harmony/ 原生工程可随时重建，受管文件漂移有保护；
• 双 React 共存：iOS/Android 用官方 react，Harmony 用 react-harmony（alias [email protected]）+ RNOH 0.84，打包零侵入；
• 诚实分级：能力矩阵区分 verified / preview / experimental，验收范围如实标注（支持矩阵）。

署名与上游致谢见 NOTICE.md。

特性

• 一体化 CLI：doctor（能力分级 + JSON 报告 + CI 退出码）/ env / create / init / prebuild（CNG，--check/--clean/--with-rnoh-host）/ sync / install / uninstall / scan / list / bundle / modules list
• 受管产物保护：autolinking 注册文件（RNOHPackagesFactory.ets/.h、autolinking.cmake）漂移检测、事务写入与回滚、--force 覆盖前自动备份
• CNG 工程壳生成：由 app.json 的 harmony 块生成 harmony/ DevEco 工程壳（AppScope/entry/hvigor/oh-package/module.json5/权限与 reason 资源/图标 SVG）
• 双 React 共存：EXPO_METRO_TARGET=harmony 时把 react 重定向到 react-harmony（npm alias [email protected]），iOS/Android 打包零侵入
• 能力分级：每个依赖模块给出 verified / preview / experimental 与缺失适配包的 nextAction，支持矩阵可机器校验（tests 保证 compat-table 与 capabilities 分组一致）
• 平台后缀：harmony 平台注册后可写 .harmony.tsx / .harmony.ts，业务代码用 Platform.OS === 'harmony' 判断

支持基线

| 项 | 值 | | --- | --- | | Expo SDK | 55（expo@~55.0.26） | | React Native | 0.83.6（iOS/Android 侧） | | RNOH | @react-native-oh/[email protected] + @rnoh/[email protected] | | React（Harmony） | react-harmony（npm alias → [email protected]） | | HarmonyOS SDK 声明口径 | compatibleSdkVersion 23 / targetApiVersion 24（harmony 块可覆盖） | | 工具链 | DevEco Studio + OHPM + Hvigor + HDC（env / doctor 会逐项检查） |

快速开始

本工具已发布到 npm：@oh-expo/expo-harmony（bin 命令名 expo-harmony）。安装：

npm install -D @oh-expo/expo-harmony    # 或 pnpm add -D @oh-expo/expo-harmony

发布与门禁细节见 docs/npm-release.md。本地体验可直接使用本仓库：

git clone https://atomgit.com/OH-Expo/expo-harmony.git
cd expo-harmony
pnpm install && pnpm build
./dist/cli.js --help

在目标工程中使用（已安装 CLI 后）：

# 1. 创建新工程（Expo SDK 55 + RNOH 0.84 基线，含 harmony 平台与 metro 分流配置）
npx expo-harmony create my-app
cd my-app
pnpm install

# 2. 生成 HarmonyOS 原生工程壳（CNG，配置驱动）
pnpm prebuild:harmony
# 或对已有 Expo 工程注入基线：
npx expo-harmony init

# 3. 诊断与校验
pnpm doctor:harmony        # 退出码 0 通过 / 1 失败 / 2 仅警告，可接 CI
pnpm check:harmony         # 校验 harmony/ 与 app.json 是否同步（prebuild --check）

随后：在 DevEco Studio 打开 harmony/ 目录 → 按项目内 docs/HARMONY.md 接入 RNOH 宿主 → 运行到真机/模拟器。

常用命令速查（完整见 docs/guide.md）：

| 命令 | 作用 | | --- | --- | | expo-harmony doctor [--strict] [--target-tier X] | 环境 + 项目 + 能力分级诊断，写 .expo-harmony/doctor-report.json | | expo-harmony env | 工具链环境检查（node/ohpm/hvigor/hdc/DevEco） | | expo-harmony create <dir> | 创建三端工程并生成 harmony/ 壳 | | expo-harmony init | 向已有工程注入基线（配置/scripts/docs/manifest/prebuild） | | expo-harmony prebuild [--check] [--clean] [--with-rnoh-host] | CNG 生成/更新 harmony/ | | expo-harmony sync [--force] [--dry-run] | 重写受管 autolinking 注册文件 | | expo-harmony install/uninstall/scan/list <pkg> | 兼容表驱动的依赖管理 | | expo-harmony bundle [--dev] | EXPO_METRO_TARGET=harmony Metro 导出到 rawfile | | expo-harmony modules list | 依赖模块的 Harmony 支持情况 |

能力分级

doctor / 支持矩阵将每个能力分为四档，详见 docs/support-matrix.md：

| 分级 | 语义 | 代表 | | --- | --- | --- | | ✅ verified | 链路/实机验收达成（上游或 toolkit 验收） | expo-router、expo-linking、expo-constants、react-native-reanimated(+worklets)、react-native-svg | | 🟡 preview | 上游已移植或 toolkit preview 在案，本仓库基线尚未二次实机复验 | expo-asset、expo-camera、expo-file-system、expo-font、react-native-gesture-handler 等 | | 🟠 experimental | 仅 fallback/桥接骨架或存在功能限制 | react-native-webview、expo-image-picker、expo-location、expo-notifications 等 | | ⛔ unsupported | 无公开适配包 | 需按 nextAction 评估/屏蔽 |

资料获取

• AtomGit：OH-Expo/expo-harmony（本仓库，主站点）
• RN / HarmonyOS 生态（AtomGit 优先）：CPF-RN 组织（RN 鸿蒙适配与 TPC 适配包，如 rnoh_test / rn_ohfeatures / rntpc_*）与 OpenHarmony 官方文档

文档

• 开发者上手指南（Getting Started）：从零创建 / 已有工程集成 / 配置 / 构建 / 真机运行的完整分步
• 使用指南（命令总览与工作流）
• RNOH 宿主接入分步指导（真机运行 RN bundle 前置：EntryAbility 桥接/RNApp/证据回填）
• 支持矩阵
• 架构说明（含 roadmap 与扩展点）
• npm 发布说明（发布形态：@oh-expo/expo-harmony，pnpm release:check 门禁）
• 能力看板
• NOTICE（署名与致谢）

License

MIT © 2026 OH-Expo 与贡献者（见 LICENSE）。上游致谢见 NOTICE.md。