NDK环境变量配置的核心只有三步：把解压后的NDK根目录写成ANDROID_NDK_HOME，把这个目录追加进PATH，然后重开终端执行ndk-build -v验证。,都是不同系统下的路径写法与排错细节。
配置前先弄清楚：NDK需要哪几个环境变量
很多人一上来就照着旧教程抄，结果抄了一堆用不上的变量，先把每个变量的作用搞明白,后面改起来才不会乱。
ANDROID_NDK_HOME：指向NDK根目录，Gradle、CMake以及部分构建脚本会读取它,是目前比较通用的写法。ANDROID_NDK_ROOT：老项目和老脚本里常见，作用和上面基本一致，有些构建系统只认这个名字,两个都配上最省心。PATH：让终端能直接找到ndk-build,不用每次写完整路径。NDK_TOOLCHAIN类变量：只在少数老版本NDK或交叉编译脚本里出现,新版本NDK基本不需要单独设置。
| 变量名 | 作用 | 是否必须 |
|---|---|---|
ANDROID_NDK_HOME |
指向NDK根目录 | 建议配置 |
ANDROID_NDK_ROOT |
兼容老脚本 | 建议配置 |
PATH追加NDK目录 |
命令行直接调用ndk-build |
必须 |
ANDROID_NDK |
部分CMake工程使用 | 视项目而定 |
业内专家指出，NDK从r19之后工具链结构变化较大，网上大量r10、r12时期的教程已经不再适用，照抄容易出现“变量配了但命令找不到”的情况。
NDK环境变量怎么配置？Windows与macOS的操作差异
Windows下NDK环境变量配置的完整步骤
先提醒一句：NDK解压路径不要带中文、空格和特殊符号，D:androidndk25.2.9519653这类纯英文路径最稳。
- 右键“此电脑”，进入“属性”，打开“高级系统设置”，点击“环境变量”。
- 在“系统变量”区域新建一项，变量名填
ANDROID_NDK_HOME，变量值填NDK根目录，例如D:androidndk25.2.9519653。 - 再新建一项
ANDROID_NDK_ROOT，值同上,照顾老脚本。 - 找到
Path，编辑后新增一行%ANDROID_NDK_HOME%,不要删掉原有内容。 - 一路确定保存，关掉所有已打开的cmd、PowerShell和IDE。
- 重新打开cmd，依次执行
echo %ANDROID_NDK_HOME%和ndk-build -v,能看到版本号就说明生效。
如果使用的是Android Studio自动下载的NDK，路径通常在C:Users用户名AppDataLocalAndroidSdkndk版本号，把变量指向这个目录即可,不必把NDK复制到别处。
macOS和Linux下NDK环境变量配置的写法
macOS新版默认使用zsh，配置文件是~/.zshrc；Linux和部分老Mac用~/.bashrc或~/.bash_profile，先确认自己用的是哪个,再往里写。
export ANDROID_NDK_HOME=/Users/yourname/Library/Android/sdk/ndk/25.2.9519653 export ANDROID_NDK_ROOT=$ANDROID_NDK_HOME export PATH=$PATH:$ANDROID_NDK_HOME
保存后执行source ~/.zshrc，再用echo $ANDROID_NDK_HOME和ndk-build -v确认，Linux上如果希望所有用户生效，可以写进/etc/profile.d/ndk.sh，但这属于系统级改动,个人开发机没必要。
两种系统的关键差异对比
| 对比项 | Windows | macOS / Linux |
|---|---|---|
| 配置入口 | 系统环境变量面板 | Shell配置文件 |
| 路径分隔符 | 反斜杠，建议用正斜杠 | 正斜杠 |
| 生效方式 | 重开终端 | source或重开终端 |
| 常见坑 | 用户变量与系统变量混淆 | 改错配置文件 |
NDK环境变量配置后不生效怎么办
这是搜索量很高的一类问题，九成情况出在下面几个点上,按顺序排查基本能定位。
- 终端没重开：环境变量在进程启动时读取，改完必须新开窗口,IDE内置终端也要重启IDE。
- 变量名拼错：
ANDROID_NDK_HOME少个字母、多一个下划线都无效，用echo或set回显确认。 - Path没保存成功：Windows上编辑Path时容易点成“取消”,重新打开面板看那一行是否还在。
- 用户变量和系统变量放错位置：只对当前用户生效就放用户变量,需要全局可用就放系统变量。
- 路径含空格或中文：某些构建脚本解析时会截断,换纯英文无空格路径。
- 多版本冲突：PATH里同时存在两个NDK路径，排在前面的优先，用
which ndk-build或where ndk-build看实际调用的是哪个。
如果ndk-build能跑但Gradle仍报找不到NDK，问题通常不在环境变量，而在项目配置,往下看。
Android Studio项目里，环境变量和Gradle配置谁说了算
local.properties与ndkVersion的正确写法
Android Studio构建时优先读项目配置，环境变量主要服务于命令行，老项目里的ndk.dir早已废弃，现在推荐在模块的build.gradle里写：
android {
ndkVersion "25.2.9519653"
}
local.properties里只保留sdk.dir即可，也就是说，IDE里能正常构建，不代表命令行能跑；反过来也一样,两边都要照顾到。
纯命令行编译场景
用CI脚本、Jenkins或者自己写Shell编译so库时，环境变量就是唯一依据，这时要确保构建机上ANDROID_NDK_HOME指向的版本与项目ndkVersion一致，否则会出现链接错误或ABI不匹配，行业共识认为，构建环境里固定NDK版本、不依赖“最新版”,能显著减少莫名其妙的编译失败。
多版本NDK共存与免安装版的处理方式
一个项目用r21，另一个用r26，是常见需求,做法不复杂：
- 把不同版本解压到各自独立目录,目录名带上版本号。
- 环境变量只指向“当前默认版本”,需要切换时改一次变量值。
- 更省事的办法是写两个小脚本，分别
export不同路径，用的时候source一下。 - 免安装版NDK本质上就是压缩包，解压即用，不需要运行安装程序,配置方式与上面完全一致。
据Android官方文档说明，NDK版本与Gradle插件版本存在兼容关系，跨版本差距过大时，即使环境变量配对了，构建也可能失败,所以切版本前先看项目要求。
几个容易被忽略的细节
- 下载源问题：国内网络直连下载NDK经常中断，多数开发者会配置镜像源或使用SDK Manager的分片下载，配置本身不受影响,但下载环节容易卡住。
- 权限问题：Linux和macOS上如果NDK目录属主是root，普通用户执行
ndk-build会报权限错误，用chmod或改属主解决。 - 要不要花钱找人配：这属于基础操作，找人代配NDK环境变量一般在几十元区间，但照着步骤自己走一遍通常十分钟内能完成,没必要付费。
- 验证顺序：先
echo变量，再ndk-build -v，最后跑一次项目构建,三层都通过才算真正配好。
Q&A：NDK环境变量配置常见疑问
Q1：只配ANDROID_NDK_HOME不配ANDROID_NDK_ROOT可以吗？
多数新项目可以，但一些老脚本和第三方构建系统只认ANDROID_NDK_ROOT，两个都配不冲突,成本也只是一行变量。
Q2：Android Studio自带的NDK还需要单独配环境变量吗？
如果在IDE里点运行就能构建，可以不配，但只要涉及命令行编译、写CI脚本或使用ndk-build，就需要把IDE里的NDK路径写进环境变量,否则终端找不到命令。
Q3：配置完成后ndk-build -v有输出，但Gradle仍报NDK缺失，是什么原因？
这种情况说明环境变量已经生效，问题出在项目侧：检查build.gradle里的ndkVersion是否与本地已安装版本完全一致，以及local.properties中的sdk.dir是否指向正确的SDK根目录,两者匹配后构建即可恢复正常。