Win迁移Mac后React Native Debugger安卓调试启动报错712/303

项目从Windows环境迁移到MacOS后，启动调试时触发报错：提示“未匹配到所有成功模式”，代表react-native run-android命令执行失败，伴随错误码712、303，可通过VS Code的「视图->切换输出->React Native」「视图->切换输出->React Native: Run android」窗口获取日志，按以下步骤排查解决：

1. 清理跨系统残留的硬编码缓存文件 #

Windows环境下生成的构建缓存自带Windows绝对路径，直接在Mac上复用会直接中断构建流程，需全部清理：

• 删除项目根目录下的node_modules文件夹，重新执行依赖安装，拉取匹配Mac环境的对应依赖包
• 进入项目的android目录，依次执行操作：
  • 执行./gradlew clean清理历史构建产物
  • 执行./gradlew --stop停止残留的gradle守护进程
  • 删除目录下的.gradle、build、app/build三个文件夹，这类目录存储的Windows构建临时文件无法在Mac环境下正常解析
• 重置adb连接：执行adb kill-server后再执行adb start-server，避免残留的adb进程卡住调试流程

2. 修正Mac环境专属路径配置 #

项目从Windows迁移后，和系统绑定的本地路径配置全部失效，是触发712错误的最高发原因：

• 检查android/local.properties文件：该文件为Windows端构建时自动生成，内部硬编码了Windows的Android SDK路径，Mac上必须修改为本地实际的SDK路径，格式参考：sdk.dir=/Users/你的本地用户名/Library/Android/sdk
• 核对本地环境变量：确认ANDROID_HOME指向本地Android SDK路径，JAVA_HOME匹配React Native版本要求的JDK版本（0.70+版本需JDK17，0.6x版本需JDK11）
• 手动在项目根目录终端执行npx react-native run-android，直接获取真实构建报错：VS Code插件提示的712、303为通用兜底错误码，本身不显示具体构建原因，终端输出的日志才是定位问题的核心依据

3. 调试配置适配 #

现有launch.json未针对跨系统场景做参数适配，容易触发“未匹配到成功模式”的误判：

• 对普通安卓调试配置，补充preLaunchTask关联本地安卓构建任务，避免VS Code插件空等构建完成信号，触发模式匹配失败的报错。参考修正后的配置结构：

  {
      "version": "0.2.0",
      "configurations": [
          {
              "name": "Debug Android Hermes - Experimental",
              "cwd": "${workspaceFolder}",
              "type": "reactnativedirect",
              "request": "launch",
              "platform": "android",
              "preLaunchTask": "Run android"
          },
          {
              "name": "Debug Android",
              "cwd": "${workspaceFolder}",
              "type": "reactnative",
              "request": "launch",
              "platform": "android",
              "preLaunchTask": "Run android"
          }
      ]
  }
  

• Hermes调试模式下，提前确认项目的Hermes版本和VS Code React Native插件的experimental调试能力匹配，避免触发303端口连接失败
• 启动调试前确认安卓真机/模拟器已打开USB调试，执行adb devices能正常识别到设备序列号，避免插件误判启动失败

4. 特殊场景补查 #

• 检查android/app/build.gradle配置文件，排查是否有Windows端硬编码的绝对路径依赖（比如本地so库路径、自定义maven仓库的Windows路径），这类配置在Mac上会直接读不到资源导致构建失败
• 确认本地安卓SDK已安装对应项目要求的build-tools版本、platform版本，避免SDK组件缺失触发构建中断

内容的提问来源于stack exchange，提问作者Erkan Kılıç