Technical Guide: Resolving ANDROID_HOME Environment Variable Configuration Errors in Cordova/PhoneGap

Problem Background and Error Analysis

During Cordova or PhoneGap mobile application development, when attempting to build the Android platform, developers frequently encounter the following error message: Error: ANDROID_HOME is not set and "android" command not in your PATH. You must fulfill at least one of these conditions. This error indicates that the system cannot locate the Android SDK installation path, preventing the build tools from executing properly.

Environment Variable Configuration Principles

The ANDROID_HOME environment variable serves to inform build tools of the Android SDK installation location. When this variable is not correctly set, Cordova cannot locate the necessary build tools and platform files. The PATH environment variable needs to include Android SDK tool directories to ensure the system can recognize commands like android.

Windows Platform Configuration Solution

For Windows operating systems, configuration needs to be done through Command Prompt or the system environment variables interface. Here are the specific configuration steps:

set ANDROID_HOME=C:\Program Files\Android\android-sdk
set PATH=%PATH%;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools

In the above code, the first line sets the ANDROID_HOME variable to point to the Android SDK installation directory, while the second line adds the SDK tool directories to the system PATH. Note that backslashes in the path require proper escaping.

macOS Platform Configuration Solution

In macOS systems, environment variable configuration requires executing the following commands through Terminal:

export ANDROID_HOME=/Users/username/android-sdk-macosx
export PATH=${PATH}:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

Here, the export command is used to set environment variables, and the ${PATH} syntax preserves the original PATH variable content. Path separators in macOS use colons instead of semicolons.

Persistence Configuration Methods

Temporarily set environment variables are only valid for the current session and will be lost after restart. To achieve permanent configuration, the setup commands need to be added to appropriate configuration files:

• Windows: Through the environment variables settings in System Properties, or by modifying the registry
• macOS: Add export commands to ~/.bash_profile or ~/.zshrc files

Permission Management and Troubleshooting

Based on experiences from reference articles, permission issues are also significant causes of build failures. When project directory permissions are improperly set, build errors may still occur even with correct environment variable configuration.

Solutions include:

1. Check read-write permissions of project directories, ensuring the current user has sufficient privileges
2. Avoid using sudo commands for Cordova operations, as this may cause permission confusion
3. If encountering permission issues, try removing and re-adding the Android platform: ionic platform remove android && ionic platform add android

Verifying Configuration Correctness

After configuration completion, verify whether environment variables are set correctly using the following commands:

echo $ANDROID_HOME  # macOS/Linux
echo %ANDROID_HOME%  # Windows
android --version   # Verify android command availability

If the output displays the correct SDK path and version information, the configuration is successful.

SDK Version Compatibility Considerations

Ensure the installed Android SDK version is compatible with Cordova requirements. Typically, Android SDK Tools, Platform-tools, and at least one Android platform version need to be installed. Necessary components can be installed through Android SDK Manager.

Summary and Best Practices

Correctly configuring ANDROID_HOME and PATH environment variables is a fundamental requirement for Cordova/PhoneGap development. Through systematic configuration methods and strict permission management, build errors can be effectively avoided. It is recommended that developers complete environment configuration during the initial project phase and standardize environment settings in team development to ensure project buildability and maintainability.