React Native 移动项目目录导致的 Android 编译失败问题及解决方案

1. 问题背景与现象

在开发 React Native 项目时，有时我们需要整理文件夹，将项目从一个目录移动到另一个目录（例如从 Downloads 移动到了 Documents）。但是，在移动目录后，当我们尝试运行 yarn android 启动项目时，可能会遇到类似以下的红屏或终端报错：

text 复制代码

FAILURE: Build failed with an exception.

* What went wrong:
Configuring project ':react-native-mmkv' without an existing directory is not allowed. The configured projectDirectory '/Users/xxx/Downloads/RNDemo/MyApp/node_modules/react-native-mmkv/android' does not exist, can't be written to or is not a directory.

2. 问题原因分析

从报错信息可以明显看出，Gradle 在构建时去寻找了旧的绝对路径。

这是因为 React Native 的构建生态中包含了多层缓存（Metro 缓存、Gradle 构建缓存、Node 模块缓存等）。在执行 yarn install 或初次构建时，这些工具会将当前依赖的绝对路径写入到缓存或 .cxx、.gradle 等中间文件中。当我们直接在文件系统中移动项目文件夹后，这些缓存并没有自动更新。因此，当 Gradle 尝试配置如 react-native-mmkv 这样的原生依赖模块时，依然会去读取旧路径，最终导致"目录不存在"的致命错误。

3. 终极解决方案

遇到这类问题，核心解决思路就是**"彻底清理各层缓存，并重新生成配置"**。具体步骤如下：

第一步：清理依赖和打包器缓存

首先，删除 node_modules，并清理 Watchman 和 Metro 的缓存，防止打包器保留旧的路径映射：

bash 复制代码

# 删除 node_modules
rm -rf node_modules

# 清除 Watchman 监听和 Metro 缓存
watchman watch-del-all
rm -rf /tmp/metro-*

第二步：清理 Android 构建缓存

进入项目根目录，手动删除 Android 目录下的各级构建产物和缓存文件：

bash 复制代码

rm -rf android/.gradle
rm -rf android/build
rm -rf android/app/build
rm -rf android/.cxx
rm -rf android/app/.cxx

第三步：重新安装依赖并深度 Clean

重新安装项目的 npm 依赖，并利用 Gradle 自身的 clean 任务再做一次清理：

bash 复制代码

# 重新安装依赖（如果您使用的是 npm，请换成 npm install）
yarn install

# 进入 android 目录并执行 gradle clean
cd android && ./gradlew clean

第四步：重新运行项目

完成上述所有步骤后，回到项目根目录，重新启动 Android 编译：

bash 复制代码

yarn android

此时，所有的路径都会基于当前项目的新位置重新生成，项目即可成功运行！

4. 总结

在 React Native 开发中，缓存问题是导致各种"玄学"编译错误的罪魁祸首之一。只要涉及项目路径变更、Node 版本大改或依赖库的重大升级，第一反应都应该是：清缓存、删依赖、重新安装。掌握这套标准的"大清洗"连招，可以帮你节省大量排查环境问题的时间。