文档模板：v0.4.2

简体中文 | English

本项目基于 react-native-config 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-config 版本所属关系如下：

| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 | | ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-config | ~ 1.7.0（开发中） | Gitcode Releases | 0.82./0.84. | 否 | API12+ | 1.6.1 | master | | @react-native-ohos/react-native-config | ~ 1.6.0 | Gitcode Releases | 0.77.* | 否 | API12+ | 1.5.5 | br_rnoh0.77 | | @react-native-oh-tpl/react-native-config | ~ 1.5.3-0.0.3 | Gitcode Releases | 0.72.* | 否 | API12+ | 1.5.3 | br_rnoh0.72 |

简介

将 .env 中的配置变量暴露给 React Native 应用，便于按 12-factor 方式管理环境配置。

HarmonyOS 侧在宿主构建期由 harmony/config/hvigorfile.ts 读取 .env（或 ENVFILE / buildProfileFields 指定的文件），生成 BuildConfig.ts；TurboModule ConfigNativeModule.getConfig() 把常量交给 JS，默认导出为 Config 对象。本库不提供 HAR、不支持 Autolink，需将源码模块拷入宿主 harmony 并手动注册。

请记住，此模块不会混淆或加密机密，因此请勿将敏感密钥写入 .env。移动应用中的密钥几乎无法防止逆向，请在设计应用和 API 时牢记这一点。

下载安装

进入到工程目录并输入以下命令：

npm

# 0.72
npm install @react-native-oh-tpl/react-native-config
# 0.77 / 0.82 / 0.84
npm install @react-native-ohos/react-native-config

yarn

# 0.72
yarn add @react-native-oh-tpl/react-native-config
# 0.77 / 0.82 / 0.84
yarn add @react-native-ohos/react-native-config

Link

| | 是否支持autolink | RN框架版本 | |--------------------------------------|----------------|-----------| | ~ 1.7.0 （开发中） | No | 0.82 / 0.84 |

本库各版本均不支持 Autolink，必须按下方 ManualLink 完成原生接入。

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  "overrides": {
    "@rnoh/react-native-openharmony": "^0.72.38" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

2. 引入原生端代码

该库仅支持源码形式引入，不提供 HAR。

目前 DevEco Studio 不支持通过源码引入外部 module，请将源码改成 harmony 工程的内部模块。通用步骤也可参考直接链接源码说明。

[!TIP] 源码位于三方库安装路径的 harmony 文件夹下。

把 <RN工程>/node_modules/@react-native-ohos/react-native-config/harmony/ 目录下的源码模块 config 复制到 harmony 工程根目录下。

在 harmony 工程根目录的 build-profile.template.json5（若存在）和 build-profile.json5 添加以下模块：

modules:[
  ...
  {
    name: 'config',
    srcPath: './config',
  }
]

打开 entry/oh-package.json5，添加以下依赖：

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/react-native-config": "file:../config"
  }

点击右上角的 sync 按钮，或在终端执行：

cd entry
ohpm install

3. 运行 Codegen 生成 C++ 桥接代码

[!IMPORTANT] 该库从 1.7.0 版本开始使用 Codegen 生成 C++ 桥接代码，取代了之前手动编写的 C++ 实现。

在 RN 工程根目录下执行 codegen 命令：

npm run codegen

该命令会读取 codegen/NativeConfigModule.ts 中的 Spec 接口定义，自动生成以下文件：

• harmony/entry/src/main/cpp/generated/ConfigNativeModule.cpp — C++ 方法注册
• harmony/entry/src/main/cpp/generated/ConfigNativeModule.h — C++ 头文件
• harmony/entry/src/main/cpp/generated/RNOHGeneratedPackage.h — C++ Package 注册（包含 ConfigNativeModule 的 TurboModule 注册）

[!TIP] 每次修改 Spec 文件后，都需要重新运行 npm run codegen 同步 C++ 代码。

4. 在 ArkTS 侧引入 RNConfigPackage

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

import type { RNPackageContext, RNPackage } from 'rnoh/ts';
  ...
+ import { RNConfigPackage } from '@react-native-ohos/react-native-config/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SamplePackage(ctx),
+   new RNConfigPackage(ctx)
  ];
}

5. 在 C++ 侧使用 Codegen 生成的 Package 注册

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "RNOHPackagesFactory.h"
+ #include "generated/RNOHGeneratedPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    const std::vector<std::shared_ptr<Package>> ManualLinkingPackage =  {
+       std::make_shared<RNOHGeneratedPackage>(ctx),
        // ... 其他 Package
    };
}

[!IMPORTANT] 配置了 RNOHGeneratedPackage 后，请勿再手动注册 RNConfigPackage 的 C++ 版本。C++ 侧的注册由 codegen 自动生成的 RNOHGeneratedPackage 负责，ArkTS 侧的 RNConfigPackage 仍然需要，两者分工不同。

运行

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

1. RNOH: 0.72.20; SDK: HarmonyOS NEXT Developer Beta1; IDE: DevEco Studio 5.0.3.200; ROM: 3.0.0.18;
2. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;
3. RNOH: 0.82.25; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;
4. RNOH: 0.84.2; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;

权限要求

本库本身无特殊权限。若应用根据 .env 中的地址发起网络请求，需在 entry/src/main/module.json5 中申请：

requestPermissions: [
  {
    name: "ohos.permission.INTERNET",
  },
],

编译运行API要求（如有）

[!TIP] 当前三方库所有版本均已实现版本隔离，支持在 API12+ 工程编译，及 API12+ ROM 运行。

其他限制

• 不支持 Autolink，不提供 HAR，必须源码拷入宿主 harmony 并手动注册。
• .env 内容会写入构建产物 BuildConfig.ts，不会加密；请勿存放密钥、Token 等敏感信息。
• 默认从 RN 工程根目录读取 .env；多环境需通过 ENVFILE 或 buildProfileFields 指定文件。

使用示例

在 React Native 应用程序的根目录中创建一个 .env 文件：

API_URL=https://myapi.com
ENV=development

然后从应用中访问这些变量。使用时 import 的库名不变：

[!WARNING] 使用时 import 的库名不变，仍为 react-native-config。

import React from 'react';
import {StyleSheet, Text, View} from 'react-native';
import Config from 'react-native-config';

const App = () => {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>ENV={Config.ENV}</Text>
      <Text style={styles.text}>API_URL={Config.API_URL}</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
  },
  text: {
    fontSize: 20,
    textAlign: 'center',
    margin: 10,
    color: '#111111',
  },
});

export default App;

使用说明

读取配置

index.js 通过 TurboModule ConfigNativeModule.getConfig() 取得构建期写入的键值对，并默认导出为 Config 对象。属性名与 .env 中的键一致：

import Config from 'react-native-config';

Config.API_URL; // 'https://myapi.com'
Config.ENV;     // 'development'

也可使用命名导出（类型定义见 index.d.ts）：

import { Config } from 'react-native-config';

多环境

将不同环境的配置保存在不同文件中：.env.staging、.env.production 等。默认情况下从 .env 读取。

优先级（由 harmony/config/hvigorfile.ts 的 defineBuildConfig 决定）：

1. 进程环境变量 ENVFILE（值为相对 RN 工程根目录的文件名，例如 .env.staging）
2. harmony/build-profile.json5 中 products[].buildOption.arkOptions.buildProfileFields，key 为小写构建类型（debug / release），value 为对应 env 文件名
3. 默认 .env

使用 ENVFILE（命令行，不推荐日常开发）

在 CMD 窗口中，先从 RN 工程根目录 cd harmony，停止守护进程后再设置 ENVFILE 并构建。node.exe 与 hvigorw.js 路径需改为本机 DevEco Studio 安装目录：

"D:\DevEcoStudio\tools\node\node.exe" "D:\DevEcoStudio\tools\hvigor\bin\hvigorw.js" --stop-daemon-all

set ENVFILE=.env.staging&&"D:\DevEcoStudio\tools\node\node.exe" "D:\DevEcoStudio\tools\hvigor\bin\hvigorw.js" --mode module -p module=entry@default -p product=default -p requiredDeviceType=phone assembleHap --analyze=normal --parallel --increm

注意：ENVFILE= 后不要加空格。为保证环境变量与构建在同一进程，不要在 DevEco Studio 内置终端用 hvigor 命令构建。

建立映射（推荐）

在 harmony 工程根目录的 build-profile.json5 中配置：

"products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "debug": ".env.development",
              "release": ".env.production"
            }
          }
        }
      }
    ]

接口说明

[!TIP] "Platform" 列表示该能力在原三方库上支持的平台。

[!TIP] "HarmonyOS Support" 列为 yes 表示 HarmonyOS 平台支持；no 表示不支持；partially 表示部分支持。使用方法跨平台一致。

本库无 UI 组件，JS 侧导出配置对象；原生侧通过 TurboModule 提供 getConfig。

导出对象

| 名称 | 参数类型 | 必填 | 平台 | HarmonyOS Support | 描述 | | ---- | -------- | ---- | ---- | ----------------- | ---- | | Config | NativeConfig（{ [name: string]: string \| undefined }） | no | Android/iOS | yes | 默认导出。属性名及其值对应 .env 中定义的键值对 |

API

| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | HarmonyOS Support | 描述 | | ---- | ---- | -------- | ------ | ---- | ---- | ----------------- | ---- | | getConfig | function | / | Record<string, string> | no | Android/iOS | yes | TurboModule ConfigNativeModule 方法。读取构建期生成的 BuildConfig 并返回全部配置。JS 默认导出已调用该方法，一般无需直接使用 |

遗留问题

无

其他

无

目录结构

/rntpc_react-native-config
├── codegen
│   └── NativeConfigModule.ts   # TurboModule Spec（codegen 输入）
├── harmony
│   └── config                  # 鸿蒙适配源码模块（无 HAR，不支持 autolink）
│       ├── Index.ets           # 模块入口
│       ├── hvigorfile.ts       # 读取 .env 并生成 BuildConfig.ts
│       ├── BuildConfig.ts      # 构建产物
│       └── src/main/ets
│           ├── RNConfigPackage.ts
│           └── RNConfigTurboModule.ts
├── index.js                    # JS 入口，默认导出 Config
├── index.d.ts
├── example                     # 示例工程
├── README.md
├── README_EN.md
└── LICENSE

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR。

开源协议

本项目基于 The MIT License (MIT)，请自由地享受和参与开源。