1. 环境准备与工具链配置在Windows系统上搭建OpenHarmony版React Native开发环境需要先完成基础工具链的安装。与传统的React Native开发不同这里涉及到OpenHarmony特有的工具和依赖项。1.1 系统环境要求开发机需要满足以下最低配置Windows 10 64位专业版/企业版版本1903或更高8GB以上内存推荐16GB100GB可用磁盘空间用于存放OpenHarmony源码和构建缓存管理员权限的账户注意家庭版Windows可能缺少部分Hyper-V功能建议使用专业版。如果使用虚拟机需要确保嵌套虚拟化已开启。1.2 开发工具安装核心工具清单及安装要点Node.js选择LTS版本当前推荐16.x安装时勾选Automatically install the necessary tools选项完成后执行npm install -g yarn安装YarnPython必须使用3.8.x版本不兼容3.9安装时勾选Add Python to PATH需要额外安装pywin32pip install pywin32JDKOpenHarmony要求JDK 8建议使用Azul Zulu版本设置JAVA_HOME环境变量指向安装目录在Path中添加%JAVA_HOME%\binDevEco Studio华为提供的OpenHarmony IDE下载时选择Windows(64-bit)版本安装时勾选Add launchers dir to the PATHDocker Desktop用于运行OpenHarmony编译环境安装后需要在设置中启用WSL 2后端分配至少4GB内存给Docker1.3 环境变量配置需要添加以下关键环境变量# Node.js相关 NODE_PATH%AppData%\npm\node_modules # OpenHarmony相关 OHOS_DIRC:\OpenHarmony OHOS_BINARY_DIR%OHOS_DIR%\prebuilts # 将以下路径加入PATH %OHOS_BINARY_DIR%\build-tools\common %OHOS_BINARY_DIR%\cli %OHOS_BINARY_DIR%\python\3.8.5\windows-x86_64验证安装是否成功node -v # 应显示v16.x python --version # 应显示3.8.x java -version # 应显示1.8.x docker --version # 应显示20.x2. OpenHarmony源码获取与编译2.1 源码下载推荐使用repo工具管理OpenHarmony源码mkdir C:\OpenHarmony cd C:\OpenHarmony # 安装git-repo curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 /usr/local/bin/repo chmod ax /usr/local/bin/repo # 初始化仓库使用--no-repo-verify跳过验证 repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-3.1-Release --no-repo-verify repo sync -c -j8 # 同步代码-j8表示8线程常见问题如果遇到gn: command not found错误需要手动下载gn工具并放入prebuilts目录2.2 编译环境准备OpenHarmony官方推荐使用Docker容器进行编译# 拉取编译镜像 docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0 # 启动容器将源码目录映射到容器内 docker run -it --name ohos-build -v C:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0在容器内执行编译# 设置编译目标以Hi3516开发板为例 ./build.sh --product-name Hi3516DV300 --ccache编译完成后镜像文件会生成在out/ohos-arm-release/packages/phone/images/目录下。2.3 模拟器安装与配置在DevEco Studio中下载OpenHarmony模拟器打开Tools Device Manager选择Local Emulator标签页下载Phone-OpenHarmony-3.1镜像配置模拟器参数!-- config.json -- { default_emulator: Phone-OpenHarmony, resolution: 720x1280, memory: 2048, cpu: 2 }启动模拟器hdc_emu start -p 5555 # 默认端口55553. React Native for OpenHarmony项目创建3.1 初始化项目使用官方模板创建项目npx react-native init MyApp --template react-native-ohpm/react-native-template-oh cd MyApp项目结构关键变化myapp/ ├── android/ # 替换为openharmony/ ├── oh-package.json # 新增的OpenHarmony依赖管理文件 ├── src/main/ets/ # OpenHarmony的ets源码目录 └── build.gradle # 替换为build-profile.json53.2 依赖安装与配置安装OpenHarmony包管理器npm install -g ohos/ohpm添加React Native OpenHarmony依赖ohpm install react-native-oh/react-native-oh配置模块映射在oh-package.json中{ dependencies: { react-native-oh/react-native-oh: file:./node_modules/react-native-oh/react-native-oh } }3.3 原生模块集成在src/main/ets/MainAbility/pages/index.ets中集成React Nativeimport { ReactNativeRoot } from react-native-oh/react-native-oh Entry Component struct Index { build() { Column() { ReactNativeRoot({ bundleName: index, componentName: MyApp }) } } }4. 开发调试流程4.1 启动开发服务器# 启动Metro打包器保持运行 npx react-native start --port 8081 # 另开终端启动OpenHarmony构建 npx react-native ohos4.2 热重载配置在metro.config.js中添加OpenHarmony支持module.exports { resolver: { sourceExts: [js, json, ts, tsx, ets], platforms: [ohos] }, transformer: { getTransformOptions: async () ({ transform: { experimentalImportSupport: false, inlineRequires: true, }, }), } };4.3 调试技巧日志查看hdc shell hilog | grep ReactNative远程调试在Chrome中访问chrome://inspect点击Configure添加localhost:8081选择React Native标签页性能分析hdc shell hiperf -d 10 -o /data/local/tmp/perf.data hdc file recv /data/local/tmp/perf.data .5. 构建与部署5.1 调试版构建npx react-native bundle --platform ohos --dev true --entry-file index.js --bundle-output build/index.jsbundle --assets-dest build5.2 发布版构建生成签名证书keytool -genkeypair -alias myapp -keyalg RSA -keysize 2048 -validity 9125 -keystore myapp.p12配置签名信息在build-profile.json5中{ app: { signingConfigs: [{ name: release, keystorePath: myapp.p12, keyAlias: myapp, keyPassword: yourpassword, storePassword: yourpassword }] } }执行发布构建npx react-native run-ohos --variantrelease6. 常见问题解决6.1 编译错误排查问题Could not find matching NDK version解决方案# 在oh-package.json中指定NDK版本 ohos: { ndkVersion: 3.1.0 }问题ETS语法解析失败解决方案# 确保DevEco Studio中安装了ETS语言插件 # 检查.ets文件编码必须为UTF-86.2 运行时问题问题红屏报错Unable to load script解决方案# 检查Metro服务器是否运行 # 确保设备与开发机在同一网络 adb reverse tcp:8081 tcp:8081问题undefined is not an object (evaluating ReactNative.requireNativeComponent)解决方案// 在入口文件顶部添加 import { registerNativeModules } from react-native-oh/react-native-oh; registerNativeModules();6.3 性能优化建议包体积优化# 使用proguard混淆代码 ohpm install ohos/proguard --save-dev渲染优化// 使用FlatList替代ScrollView // 设置initialNumToRender合理值内存管理// 在页面离开时释放资源 aboutToDisappear() { ReactNativeRoot.cleanup() }7. 进阶配置7.1 多设备适配在resources/base/profile/main_pages.json中配置多分辨率{ src: pages/index, window: { designWidth: 720, autoDesignWidth: true } }7.2 原生模块开发创建ETS模块// native/MyModule.ets Entry Component export struct MyModule { State message: string Hello from ETS build() { Column() { Text(this.message) } } }在JS端调用import { NativeModules } from react-native NativeModules.MyModule.show()7.3 持续集成GitLab CI示例配置stages: - build ohos_build: stage: build image: swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0 script: - npm install - ohpm install - npx react-native bundle --platform ohos --dev false - npx react-native run-ohos --variantrelease artifacts: paths: - build/ Windows搭建OpenHarmony版React Native开发环境指南
1. 环境准备与工具链配置在Windows系统上搭建OpenHarmony版React Native开发环境需要先完成基础工具链的安装。与传统的React Native开发不同这里涉及到OpenHarmony特有的工具和依赖项。1.1 系统环境要求开发机需要满足以下最低配置Windows 10 64位专业版/企业版版本1903或更高8GB以上内存推荐16GB100GB可用磁盘空间用于存放OpenHarmony源码和构建缓存管理员权限的账户注意家庭版Windows可能缺少部分Hyper-V功能建议使用专业版。如果使用虚拟机需要确保嵌套虚拟化已开启。1.2 开发工具安装核心工具清单及安装要点Node.js选择LTS版本当前推荐16.x安装时勾选Automatically install the necessary tools选项完成后执行npm install -g yarn安装YarnPython必须使用3.8.x版本不兼容3.9安装时勾选Add Python to PATH需要额外安装pywin32pip install pywin32JDKOpenHarmony要求JDK 8建议使用Azul Zulu版本设置JAVA_HOME环境变量指向安装目录在Path中添加%JAVA_HOME%\binDevEco Studio华为提供的OpenHarmony IDE下载时选择Windows(64-bit)版本安装时勾选Add launchers dir to the PATHDocker Desktop用于运行OpenHarmony编译环境安装后需要在设置中启用WSL 2后端分配至少4GB内存给Docker1.3 环境变量配置需要添加以下关键环境变量# Node.js相关 NODE_PATH%AppData%\npm\node_modules # OpenHarmony相关 OHOS_DIRC:\OpenHarmony OHOS_BINARY_DIR%OHOS_DIR%\prebuilts # 将以下路径加入PATH %OHOS_BINARY_DIR%\build-tools\common %OHOS_BINARY_DIR%\cli %OHOS_BINARY_DIR%\python\3.8.5\windows-x86_64验证安装是否成功node -v # 应显示v16.x python --version # 应显示3.8.x java -version # 应显示1.8.x docker --version # 应显示20.x2. OpenHarmony源码获取与编译2.1 源码下载推荐使用repo工具管理OpenHarmony源码mkdir C:\OpenHarmony cd C:\OpenHarmony # 安装git-repo curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 /usr/local/bin/repo chmod ax /usr/local/bin/repo # 初始化仓库使用--no-repo-verify跳过验证 repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-3.1-Release --no-repo-verify repo sync -c -j8 # 同步代码-j8表示8线程常见问题如果遇到gn: command not found错误需要手动下载gn工具并放入prebuilts目录2.2 编译环境准备OpenHarmony官方推荐使用Docker容器进行编译# 拉取编译镜像 docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0 # 启动容器将源码目录映射到容器内 docker run -it --name ohos-build -v C:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0在容器内执行编译# 设置编译目标以Hi3516开发板为例 ./build.sh --product-name Hi3516DV300 --ccache编译完成后镜像文件会生成在out/ohos-arm-release/packages/phone/images/目录下。2.3 模拟器安装与配置在DevEco Studio中下载OpenHarmony模拟器打开Tools Device Manager选择Local Emulator标签页下载Phone-OpenHarmony-3.1镜像配置模拟器参数!-- config.json -- { default_emulator: Phone-OpenHarmony, resolution: 720x1280, memory: 2048, cpu: 2 }启动模拟器hdc_emu start -p 5555 # 默认端口55553. React Native for OpenHarmony项目创建3.1 初始化项目使用官方模板创建项目npx react-native init MyApp --template react-native-ohpm/react-native-template-oh cd MyApp项目结构关键变化myapp/ ├── android/ # 替换为openharmony/ ├── oh-package.json # 新增的OpenHarmony依赖管理文件 ├── src/main/ets/ # OpenHarmony的ets源码目录 └── build.gradle # 替换为build-profile.json53.2 依赖安装与配置安装OpenHarmony包管理器npm install -g ohos/ohpm添加React Native OpenHarmony依赖ohpm install react-native-oh/react-native-oh配置模块映射在oh-package.json中{ dependencies: { react-native-oh/react-native-oh: file:./node_modules/react-native-oh/react-native-oh } }3.3 原生模块集成在src/main/ets/MainAbility/pages/index.ets中集成React Nativeimport { ReactNativeRoot } from react-native-oh/react-native-oh Entry Component struct Index { build() { Column() { ReactNativeRoot({ bundleName: index, componentName: MyApp }) } } }4. 开发调试流程4.1 启动开发服务器# 启动Metro打包器保持运行 npx react-native start --port 8081 # 另开终端启动OpenHarmony构建 npx react-native ohos4.2 热重载配置在metro.config.js中添加OpenHarmony支持module.exports { resolver: { sourceExts: [js, json, ts, tsx, ets], platforms: [ohos] }, transformer: { getTransformOptions: async () ({ transform: { experimentalImportSupport: false, inlineRequires: true, }, }), } };4.3 调试技巧日志查看hdc shell hilog | grep ReactNative远程调试在Chrome中访问chrome://inspect点击Configure添加localhost:8081选择React Native标签页性能分析hdc shell hiperf -d 10 -o /data/local/tmp/perf.data hdc file recv /data/local/tmp/perf.data .5. 构建与部署5.1 调试版构建npx react-native bundle --platform ohos --dev true --entry-file index.js --bundle-output build/index.jsbundle --assets-dest build5.2 发布版构建生成签名证书keytool -genkeypair -alias myapp -keyalg RSA -keysize 2048 -validity 9125 -keystore myapp.p12配置签名信息在build-profile.json5中{ app: { signingConfigs: [{ name: release, keystorePath: myapp.p12, keyAlias: myapp, keyPassword: yourpassword, storePassword: yourpassword }] } }执行发布构建npx react-native run-ohos --variantrelease6. 常见问题解决6.1 编译错误排查问题Could not find matching NDK version解决方案# 在oh-package.json中指定NDK版本 ohos: { ndkVersion: 3.1.0 }问题ETS语法解析失败解决方案# 确保DevEco Studio中安装了ETS语言插件 # 检查.ets文件编码必须为UTF-86.2 运行时问题问题红屏报错Unable to load script解决方案# 检查Metro服务器是否运行 # 确保设备与开发机在同一网络 adb reverse tcp:8081 tcp:8081问题undefined is not an object (evaluating ReactNative.requireNativeComponent)解决方案// 在入口文件顶部添加 import { registerNativeModules } from react-native-oh/react-native-oh; registerNativeModules();6.3 性能优化建议包体积优化# 使用proguard混淆代码 ohpm install ohos/proguard --save-dev渲染优化// 使用FlatList替代ScrollView // 设置initialNumToRender合理值内存管理// 在页面离开时释放资源 aboutToDisappear() { ReactNativeRoot.cleanup() }7. 进阶配置7.1 多设备适配在resources/base/profile/main_pages.json中配置多分辨率{ src: pages/index, window: { designWidth: 720, autoDesignWidth: true } }7.2 原生模块开发创建ETS模块// native/MyModule.ets Entry Component export struct MyModule { State message: string Hello from ETS build() { Column() { Text(this.message) } } }在JS端调用import { NativeModules } from react-native NativeModules.MyModule.show()7.3 持续集成GitLab CI示例配置stages: - build ohos_build: stage: build image: swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0 script: - npm install - ohpm install - npx react-native bundle --platform ohos --dev false - npx react-native run-ohos --variantrelease artifacts: paths: - build/