1. 问题现象与核心影响分析如果你正在使用 Android Studio 开发一个需要 C/C 代码支持的项目比如一个图像处理应用或者一个游戏引擎插件在尝试编译时突然在“Build”输出窗口看到一行刺眼的红色错误信息[CXX1101] NDK at 目录\Android\Sdk\ndk\22.1.7171670 did not have a source.properties file那么恭喜你你遇到了一个在 Android NDK 开发中相当典型的环境配置问题。这个错误不会让你的代码逻辑出错但它会彻底堵死你的编译流程让整个项目构建过程戛然而止。错误信息直白地告诉你Android Studio或者更准确地说是背后的 CMake 或 NDK Build 系统在你指定的 NDK 路径下找不到一个名为source.properties的关键文件。这个source.properties文件是 NDK 安装目录的“身份证”和“说明书”。它里面通常包含了该 NDK 版本的核心元数据例如Pkg.Revision修订版本号、Pkg.Desc描述信息等。构建系统如 CMake在初始化时会去读取这个文件来验证 NDK 的完整性和有效性并获取必要的配置信息。当这个文件缺失时构建系统就无法确认这个 NDK 目录是否是一个合法、可用的 NDK 发行版出于安全性和稳定性的考虑它会直接报错并中止构建。这就像你拿着一个没有芯片的身份证去过安检机器根本无法读取你的信息自然不会放行。这个问题的直接影响非常明确你无法编译任何包含原生C/C代码的 Android 模块。无论是全新的 JNI 调用还是现有的原生库链接所有依赖 NDK 的构建任务都会失败。对于开发者而言这意味着功能开发停滞、调试中断如果发生在持续集成CI环境中会导致整个自动化构建流水线报红。因此解决这个问题是恢复项目正常构建的必要前提。2. 问题根源深度剖析为什么source.properties会消失要解决问题必须先理解问题是如何产生的。source.properties文件的缺失很少是因为该文件被“意外删除”其背后往往指向更深层次的 NDK 安装或配置状态异常。根据我多年的移动端开发经验根源通常可以归结为以下三类2.1 NDK 下载或安装不完整最常见这是导致该问题的头号原因。尤其是在国内网络环境下通过 Android Studio 的 SDK Manager 在线下载 NDK 时可能会因为网络波动、代理设置不当或磁盘空间不足导致下载过程中断或文件未完全写入。NDK 是一个庞大的工具包包含编译器clang、库文件、构建脚本和元数据文件。source.properties作为元数据文件可能在下载队列的末尾如果下载提前终止它就可能丢失。另一种情况是开发者手动从官网下载了 ZIP 包进行解压如果在解压过程中被安全软件拦截、磁盘错误或解压工具异常也可能造成该文件缺失。2.2 NDK 目录被意外移动或修改Android Studio 和项目配置中记录的 NDK 路径是固定的。如果你在文件管理器中手动将ndk\22.1.7171670这个文件夹移动、重命名或者不小心删除了其中的某些文件就会破坏其完整性。更隐蔽的情况是一些系统清理软件或磁盘优化工具可能会误将source.properties这类小文件识别为“缓存文件”或“临时文件”而将其清理掉。2.3 多版本 NDK 并存导致的配置冲突许多项目为了兼容性可能会在local.properties或gradle.properties中通过ndkVersion或android.ndkPath指定一个具体的 NDK 版本路径。如果你本地安装了多个 NDK 版本例如 21.x, 22.x, 23.x并且在切换版本时配置指向了一个不完整或错误的目录也会触发此错误。有时Android Studio 的缓存包括 Gradle Daemon 缓存可能记录了旧的、无效的路径信息导致其尝试从一个错误的、不完整的位置加载 NDK。实操心得遇到此错误第一步不要急着乱改配置。先打开文件管理器导航到错误提示的路径\Android\Sdk\ndk\22.1.7171670直观地检查这个目录是否存在以及其内部结构是否完整。一个完整的 NDK 目录应该包含toolchains,platforms,sources,build等子文件夹并且在根目录下肯定存在source.properties文件。如果连这个目录都不存在那问题就更明确了。3. 系统性解决方案从验证到修复的完整流程解决[CXX1101]错误需要一个系统性的方法而不是盲目尝试。下面我提供一个从诊断到修复的完整流程你可以按顺序操作。3.1 第一步现场诊断与信息确认在开始任何修复操作前请先收集以下关键信息确认完整的 NDK 路径错误信息中给出的路径是\Android\Sdk\ndk\22.1.7171670。请注意这通常是一个相对路径或省略了盘符的路径。其完整路径通常是C:\Users\[你的用户名]\AppData\Local\Android\Sdk\ndk\22.1.7171670Windows或/Users/[你的用户名]/Library/Android/sdk/ndk/22.1.7171670macOS/Linux。打开文件管理器直接进入这个完整路径。检查目录内容进入该 NDK 版本目录后查看是否存在source.properties文件。同时感受一下目录大小一个完整的 NDK 大小通常在 1GB 以上如果目录只有几十或几百 MB那基本可以断定下载不完整。核对项目配置在 Android Studio 中打开你的项目根目录下的local.properties文件。检查sdk.dir和ndk.dir较新版本可能已弃用ndk.dir的配置。同时打开模块级build.gradle.kts或build.gradle文件在android块内检查是否有ndkVersion的设置例如android { compileSdk 34 ndkVersion 22.1.7171670 // 确认这里的版本号 }查看 SDK Manager打开 Android Studio - Settings - Appearance Behavior - System Settings - Android SDK - SDK Tools 选项卡。在这里查看 “NDK (Side by side)” 的安装状态和版本号。确认22.1.7171670这一版本是否显示为已安装或者是否有更新可用。3.2 第二步核心修复操作根据诊断结果选择以下最适合你的方案。方案A重新安装指定的 NDK 版本推荐首选这是最彻底、最一劳永逸的方法适用于绝大多数因文件缺失或不完整导致的问题。卸载现有版本在 Android Studio 的 SDK Tools 页面找到 NDK (Side by side) 列表勾选22.1.7171670这个版本然后点击右下角的 “Apply” 或 “OK”。这会弹出一个确认对话框选择 “OK” 将其卸载。等待卸载完成。重新安装卸载完成后再次勾选22.1.7171670版本或者你可以选择一个更新的稳定版本但需要同步更新项目配置点击 “Apply”。Android Studio 会开始下载并安装。注意事项下载过程中请保持网络稳定。如果遇到下载缓慢或失败可以尝试配置 Android Studio 的 HTTP 代理Settings - Appearance Behavior - System Settings - HTTP Proxy使用可靠的代理服务器。也可以手动配置 SDK Manager 使用国内镜像源但这需要修改 SDK 管理器的配置文件操作相对复杂。验证安装安装完成后再次前往文件管理器中的 NDK 目录确认source.properties文件已存在。你可以用文本编辑器打开它内容应类似Pkg.Desc Android NDK Pkg.Revision 22.1.7171670清理并重建项目在 Android Studio 中执行File - Invalidate Caches and Restart...然后选择 “Invalidate and Restart”。重启后尝试Build - Clean Project然后Build - Rebuild Project。方案B手动创建source.properties文件临时应急如果你确信 NDK 的其他部分都是完整的只是丢失了这一个文件并且急需编译可以尝试手动创建。但这只是一个临时解决方案不保证所有功能正常因为无法确认其他文件是否也完好。在\Android\Sdk\ndk\22.1.7171670\目录下新建一个文本文件命名为source.properties。用文本编辑器打开输入以下内容版本号根据你的实际情况修改Pkg.Desc Android NDK Pkg.Revision 22.1.7171670保存文件。在 Android Studio 中执行File - Invalidate Caches and Restart...和Build - Rebuild Project。方案C切换或指定一个可用的 NDK 版本如果你本地有其他完整可用的 NDK 版本可以绕过有问题的版本。检查已有版本在文件管理器中进入\Android\Sdk\ndk\目录查看有哪些子文件夹每个子文件夹代表一个 NDK 版本。进入另一个版本目录确认其包含完整的文件和source.properties。修改项目配置在模块级的build.gradle文件中将ndkVersion修改为你确认可用的版本号例如android { compileSdk 34 ndkVersion 25.1.8937393 // 更改为你已有的、可用的版本 }同步 Gradle点击 Android Studio 工具栏中的 “Sync Now”。清理并重建项目。3.3 第三步进阶排查与配置检查如果上述方案均未解决问题可能需要深入检查更隐蔽的配置。检查CMakeLists.txt配置打开你项目中的CMakeLists.txt文件。有时里面会通过-DANDROID_NDK参数硬编码 NDK 路径。确保这个路径指向一个有效的、完整的 NDK 目录。检查环境变量虽然现代 Android Studio 项目通常不依赖系统环境变量但检查一下也无妨。在终端中运行echo %ANDROID_NDK_HOME%(Windows) 或echo $ANDROID_NDK_HOME(macOS/Linux)看它是否指向了一个错误的或已损坏的路径。如果有可以尝试在系统环境变量中删除或更正它。检查 Gradle 属性文件在项目根目录或GRADLE_USER_HOME目录下的gradle.properties文件中检查是否有android.ndkPath的相关设置并确保其正确。尝试离线包安装如果网络是瓶颈可以尝试手动下载 NDK 离线包。从 Android 开发者官网的 “NDK 下载” 页面找到对应版本如 revision 22.1.7171670的 ZIP 文件例如android-ndk-r22b-windows-x86_64.zip。下载完成后完全删除旧的\ndk\22.1.7171670目录然后将 ZIP 包解压到一个临时位置最后将解压出的文件夹通常名为android-ndk-r22b整个复制到\Android\Sdk\ndk\目录下并重命名为22.1.7171670。这种方式能最大程度保证文件完整性。4. 常见问题与排查技巧实录在这一部分我汇总了几个在解决[CXX1101]错误时除了核心步骤外你很可能遇到的“衍生问题”和对应的排查技巧。这些技巧能帮你节省大量搜索和试错的时间。问题1重新安装 NDK 时SDK Manager 提示“已安装”但文件还是不完整。排查思路这通常是 Android Studio 的缓存信息有误导致其认为已安装实际上并未触发下载。解决技巧完全关闭 Android Studio。导航到 Android SDK 目录下的.temp文件夹例如C:\Users\用户名\AppData\Local\Android\Sdk\.temp清空里面的所有内容这是下载缓存。删除有问题的 NDK 目录22.1.7171670。重新启动 Android Studio打开 SDK Tools先取消勾选该 NDK 版本并 Apply确保卸载记录更新再重新勾选并 Apply。这次应该会正常开始下载。问题2按照方案C切换了ndkVersion但构建时依然报错指向旧的路径。排查思路Gradle 构建缓存或 Android Studio 的项目模型缓存未更新。解决技巧执行File - Invalidate Caches and Restart...。在项目根目录打开终端执行以下命令清理 Gradle 缓存# Windows gradlew cleanBuildCache # macOS/Linux ./gradlew cleanBuildCache如果问题依旧可以尝试删除项目根目录下的.gradle文件夹和build文件夹所有模块的然后重新同步和构建。这是一个更彻底的清理方式。问题3在 CI/CD 服务器如 Jenkins、GitLab CI上遇到此错误。排查思路CI 环境通常是干净的问题往往出在 NDK 的安装脚本或缓存机制上。解决技巧在 CI 构建脚本中在安装 Android SDK/NDK 的步骤后增加一个验证步骤。例如添加一个脚本命令来检查source.properties文件是否存在# 在 shell 脚本中 NDK_PATH$ANDROID_HOME/ndk/22.1.7171670 if [ ! -f $NDK_PATH/source.properties ]; then echo ERROR: source.properties missing in NDK! exit 1 fi考虑在 CI 中使用 Docker 镜像其中预装了完整且验证过的 Android 开发环境可以避免每次下载的不确定性。检查 CI 服务器的磁盘空间是否充足下载过程中是否被中断。问题4错误信息中的路径和我本地实际的 SDK 路径不一致。排查思路项目中的local.properties文件可能包含了错误的sdk.dir路径或者该文件被版本控制系统忽略而 CI 服务器上使用的是默认路径。解决技巧确保local.properties文件中的sdk.dir指向你本地正确的 SDK 路径。注意这个文件通常不应该提交到 Git 仓库它已在.gitignore中因为每个开发者的 SDK 安装路径可能不同。在团队协作中建议在项目的README.md或构建文档中说明如何正确设置本地 SDK 路径或者使用环境变量ANDROID_HOME来统一管理。独家避坑技巧预防胜于治疗。我个人的习惯是在项目README.md或一个专门的setup_guide.md文件中明确列出项目所需的 NDK 精确版本号例如22.1.7171670并建议团队成员通过 Android Studio 的 SDK Manager 进行安装。对于新电脑的环境搭建我会先通过 SDK Manager 安装 NDK然后立刻去文件管理器确认source.properties文件的存在将这个“确认文件存在”作为环境准备完毕的标志之一。这个简单的检查步骤能避免后续很多莫名的构建失败。