Expo 凭借其“开箱即用”的体验，成为了无数 React Native 开发者的心头好。然而当你真正决定从 Expo Go 走向 EAS 的云端构建，或者尝试在本地进行 Prebuild 时真正的“修罗场”才刚刚开始。别指望会个 React 就Neng写出靠谱的原生应用，RN ≠ 原生，这中间的鸿沟，往往由无数个报红的控制台日志填满。

今天我们就来一场深度复盘，不讲那些虚头巴脑的理论，直接上干货。这不仅是技术文档，geng是无数个深夜里我和 Gemini、ChatGPT 以及 Minimax 混战六小时后出的血泪史。Ru果你正对着 BUILD FAILED 发呆，或者对着 Gradle 的报错怀疑人生，那么这篇文章或许就是你的救命稻草。

hen多新手在引入新库时习惯性地直接敲下 npm install react-native-reanimated。这往往是噩梦的开始。Expo 的生态极其依赖版本的一致性，手动安装虽然Neng拉下Zui新的包，但极有可Neng与当前的 Expo SDK 版本不兼容。

你可Neng会遇到 Gradle 编译时疯狂报错，或者 Reanimated 库直接罢工。这时候，请务必记住一条铁律：使用 Expo 官方提供的安装命令。

npx expo install react-native-reanimated

为什么？因为 npx expo install 会自动查阅当前 SDK 版本对应的、经过验证的依赖版本。它Neng帮你避开那些因为版本不匹配导致的“玄学”问题。在安装完依赖后建议顺手跑一下检查命令：

npx expo install --check

直到命令行提示 / checks passed. No issues detected!，你才Neng稍微松一口气。这步操作Neng帮你解决 80% 的依赖冲突。记住EAS Build 和本地构建dou严格依赖 yarn.lock 或 package-lock.json，版本不一致是导致云端构建失败的头号杀手。

当你准备提交构建时eas.json 就是你的作战地图。hen多同学在本地跑得好好的，一上云端就挂，原因往往出在环境差异上。

这里有一个极易被忽视的细节：Node 版本号。本人使用 EAS Build 编译时发现，未设置 Node 版本号可Neng导致意外的编译失败。云端构建环境可Neng随时变动，为了稳定性，强烈建议在 eas.json 中写死 Node 版本。

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "node": "18.18.0" 
    },
    "production": {
      "node": "18.18.0",
      "android": {
        "buildType": "app-bundle"
      }
    }
  }
}

此外本地构建是调试神器。当你需要快速迭代时eas build --platform android --profile development --local Neng帮你省去不少排队时间。但本地构建对环境要求苛刻，确保 android/local.properties 存在且路径正确。在 Windows 下路径中的冒号和反斜杠需要转义，这简直是 Windows 开发者的专属“惊喜”。

在国内开发 Expo，网络问题就像空气一样无处不在。即便你配置了阿里云镜像，依然可Neng因为 Gradle Wrapper 下载、插件依赖或者某些特殊的 aar 包而失败。阿里云镜像无法覆盖 100% 的 Google 资源，尤其是Zui新的 NDK 或某些冷门库。

强烈建议全程挂载相关的网络工具并开启全局代理。但仅仅开启代理是不够的，Gradle 默认可Neng不走系统代理。你需要修改 android/gradle.properties，加入以下配置：

systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=7890
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=7890

注意，端口要改成你实际代理软件的端口。

不要在每个项目里改 build.gradle，那样太累且容易出错。直接在 USER_HOME/.gradle/init.d/init.gradle 放置一个脚本，全局劫持仓库地址。这招非常狠，Neng解决大部分依赖下载慢的问题。

def ALIYUN_PUBLIC = 'https://maven.aliyun.com/repository/public'
def ALIYUN_GOOGLE = 'https://maven.aliyun.com/repository/google'
def ALIYUN_PLUGIN = 'https://maven.aliyun.com/repository/gradle-plugin'
def replaceRepositoryUrl = { repo ->
    if  {
        def url = repo.url.toString
        if  || url.contains) {
            repo.setUrl
        } else if  || url.contains) {
            repo.setUrl
        } else if ) {
            repo.setUrl
        }
    }
}
allprojects {
    buildscript {
        repositories {
            all { replaceRepositoryUrl }
        }
    }
    repositories {
        all { replaceRepositoryUrl }
    }
}
gradle.settingsEvaluated { settings ->
    settings.pluginManagement {
        repositories {
            all { replaceRepositoryUrl }
        }
    }
}

这是作者踩坑报错Zui多的地方。当你kan到 CMake not found 或者 NDK version defined in... disagrees with... 时别慌。去 SDK Manager 里把对应的 CMake 和 NDK 装上。Ru果版本冲突，记得在 local.properties 或 gradle.properties 里强制指定路径，确保 Gradle 用的就是你想用的那个版本。

Expo 的 Prebuild 模式虽然生成了 android 和 ios 文件夹，但这并不意味着你Ke以随意修改里面的原生代码。每次运行 npx expo prebuild，你的修改dou可Neng被覆盖。

比如你需要修改 Android 的权限，或者修改 iOS 的 Info.plist。正确的姿势不是直接去改 AndroidManifest.xml，而是使用 Config Plugins。在 app.json 或 app.config.js 中配置插件，保证每次 prebuild douNeng生成正确的原生代码。

{
  "expo": {
    "name": "MyApp",
    "android": {
      "package": "com.company.myapp"
    },
    "plugins": 
    ]
  }
}

这里有一个关于资源处理的核心逻辑，hen多人容易踩坑。当你需要替换或加载某些资源时核心逻辑：不是 remove，而是 setUrl。 试图直接移除某些默认资源往往会导致构建系统找不到引用而崩溃，通过 URL 劫持的方式进行替换才是正解。

Ru果你在用 expo-camera，要注意版本兼容性。在 Expo 43 之后它可Neng需要 expo-face-detector 和 expo-barcode-scanner 配合才Neng正常工作，否则直接 clash。笔者曾因此被迫换回 expo-barcode-scanner。还有一个奇葩的坑，Modal 的 visible 属性Ru果立即修改可Neng会出问题，尝试等待 100ms 后再修改，往往Neng解决。

expo-av 虽然让音频处理变简单，但本地 MP3 加载失败是常有的事。明明文件就在那里它却报错找不到。这时候，检查 assetBundlePatterns 配置是否正确包含了你的资源路径。

"assetBundlePatterns": 

利用 expo-updates 模块Zuo热geng新时记得检查 checkForUpdateAsync 的逻辑。而在 Android 13+ 上，别忘了请求通知权限，否则你的推送消息将石沉大海。

import { PermissionsAndroid } from 'react-native';
const granted = await PermissionsAndroid.request(
  PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
);

当构建失败时面对几千行的日志，不要慌。按以下顺序kan：

kan顶部通常会有一个 Task failed 或 Error 的直接告诉你哪个任务挂了。