How to Configure Multiple Environments for HarmonyOS Applications

Preface

As is well known, development certificates and release certificates are not interchangeable. For those who have launched apps before, it is common knowledge that app submission rarely succeeds on the first try, and during daily updates, there are often scenarios where the app needs to be frequently released or updated. However, each app release requires switching certificates and repackaging the app.

With a large number of certificates, switching them each time becomes a tedious task. Forgetting to switch the correct certificate may lead to app rejection during submission, which is a minor issue. However, if it delays fixing a critical bug in the production environment, the consequences could be severe.

Additionally, when the environment changes, some variables (such as production server URLs) need to be adjusted accordingly. Forgetting to modify these variables can also cause significant problems.

Therefore, in development, there is a clear need to configure multiple sets of certificates and use environment variable control.

Configure Multiple Environments

We need to configure app.products in the global build-profile.json5 to package multiple product variants. Example configuration:

"products": [
  {
    "name": "default", // Ensure at least one "default" product exists in products
    "signingConfig": "default",
    "compatibleSdkVersion": "5.0.0(12)",
    "runtimeOS": "HarmonyOS",
    "buildOption": {
      "strictMode": {
        "caseSensitiveCheck": true,
        "useNormalizedOHMUrl": true
      }
    }
  },
  {
    "name": "release",
    "signingConfig": "release",
    "compatibleSdkVersion": "5.0.0(12)",
    "runtimeOS": "HarmonyOS",
    "buildOption": {
      "strictMode": {
        "caseSensitiveCheck": true,
        "useNormalizedOHMUrl": true
      }
    }
  }
]

Add a new set of signatures named release (this name needs to correspond to the signingConfig above).

Configure an additional target in the modules section to associate the phone entry with corresponding products:

{
  "name": "phone",
  "srcPath": "./entry",
  "targets": [
    {
      "name": "default",
      "applyToProducts": [
        "default"
      ]
    },
    {
      "name": "release",
      "applyToProducts": [
        "release"
      ]
    }
  ]
}

Modify the targets configuration in build-profile.json5 under the entry directory:

[
  {
    "name": "default"
  },
  {
    "name": "release"
  }
]

This completes the configuration for multiple signing profiles. To switch between different signatures, simply click the Product icon in the top-right corner.

Define Environment Variables

HarmonyOS projects are not frontend projects, so there is no .env file or --mode=production parameter.

We already know how to package multiple builds. Now, we just need to determine whether the current build is release or default to distinguish environments. Normally, we cannot directly know the current build mode, but the HAR runtime can obtain compilation parameters and generate a BuildProfile class file. Therefore, we can indirectly distinguish environments by introducing the BuildProfile file in the HAR package:

import BuildProfile from '../../../../BuildProfile';
const isRelease = (BuildProfile.BUILD_MODE_NAME as string) === 'release';

At this point, we can configure some JSON files and use the isRelease variable (or declare a mapping) to determine the current environment.

Summary

The general steps are as follows:

1. Configure multiple sets of certificates and environment variables in HarmonyOS development.
2. For multi-environment configuration, complete multiple signing configurations by editing the global build-profile.json5 and app.products, and switch signatures as needed.
3. When defining environment variables, leverage the BuildProfile file introduced at HAR runtime to determine the build environment.

Article and code version: HarmonyOS 5.0.1 Release SDK.