如何解决ionic cordova build android时环境变量未定义及JAVA_HOME缺失问题

典型报错日志 #

Checking Java JDK and Android SDK versions
ANDROID_SDK_ROOT=undefined (recommended setting)
ANDROID_HOME=undefined (DEPRECATED)
Failed to find 'JAVA_HOME' environment variable. Try setting it manually.
[ERROR] An error occurred while running subprocess cordova.
cordova.cmd build android exited with exit code 1.

解决步骤 #

配置JDK相关环境变量 #

• 确认已安装兼容版本的JDK：Ionic 6+及主流Cordova版本推荐使用JDK 11，不建议使用17及以上高版本JDK，避免Gradle兼容报错
• 找到JDK实际安装路径：
  • Windows默认无中文路径示例：C:\Program Files\Java\jdk-11.0.20
  • macOS默认路径示例：/Library/Java/JavaVirtualMachines/jdk-11.0.20/Contents/Home
• 配置系统环境变量：
  • Windows操作路径：此电脑右键→属性→高级系统设置→环境变量→系统变量栏→新建，变量名设为JAVA_HOME，变量值填入上述JDK根路径；再找到系统变量中的Path，编辑后追加%JAVA_HOME%\bin（多路径用英文分号分隔）
  • macOS/Linux操作：编辑~/.zshrc（默认终端为zsh）或~/.bash_profile，添加两行配置后保存，执行source 对应配置文件路径生效：

    export JAVA_HOME=你实际的JDK根路径
    export PATH=$JAVA_HOME/bin:$PATH
    

• 验证配置有效性：新开终端执行java -version、echo %JAVA_HOME%（Windows）/ echo $JAVA_HOME（macOS/Linux），能正常输出版本号和对应路径即为生效

配置Android SDK相关环境变量 #

• 确认已安装Android Studio或独立的Android Command Line Tools，能正常读取SDK组件
• 找到Android SDK根路径：
  • Windows默认路径示例：C:\Users\你的系统用户名\AppData\Local\Android\Sdk
  • macOS默认路径示例：~/Library/Android/sdk
• 配置系统环境变量：
  • 新建系统变量ANDROID_SDK_ROOT，变量值填入上述SDK根路径（官方推荐标准配置）
  • 为兼容旧版Cordova插件，可同步新建ANDROID_HOME变量，变量值与ANDROID_SDK_ROOT保持一致
  • 在系统Path变量中追加以下SDK子路径：platform-tools、tools、build-tools/对应稳定版本号
• 验证配置有效性：新开终端执行adb --version能正常输出版本信息，即为配置生效

常见配置失效排查点 #

• 所有环境变量配置完成后，必须完全关闭已打开的终端、IDE、本地服务进程，重新开新的终端窗口再执行构建命令，旧进程无法读取新配置的环境变量
• 禁止将JDK、Android SDK安装在带中文、特殊字符或空格的路径下，避免程序读取路径失败
• 不要直接使用Android Studio自带的jbr路径作为JAVA_HOME，该路径为IDE内置专用环境，存在兼容风险
• 执行构建前可先运行cordova requirements命令，该命令会自动检测所有构建依赖的配置情况，缺漏项会直接给出明确提示
• Windows系统执行构建时，建议以管理员权限打开终端，避免权限不足导致环境变量读取失败

内容的提问来源于stack exchange，提问作者Kairaoi Ientumoa