VSCode点击“Debug”按钮不会自动启动Metro，必须先手动运行npx react-native start并确认其监听8081端口，再点击调试；否则会超时或连接失败。
VSCode里点“Debug”但Metro根本没启动
VSCode的React Native Tools插件不会自动拉起Metro，它只负责转发调试请求。如果npm start或npx react-native start没在后台运行，点击调试按钮就会卡住、超时，甚至报ERR_CONNECTION_TIMED_OUT。
- 先手动在终端执行
npx react-native start，等看到Starting Metro Bundler和Running on http://localhost:8081再点VSCode里的调试按钮 - 不要依赖插件自动生成的
launch.json——它常把program指向node_modules/react-native/cli.js，但实际需要的是已启动的Metro服务端口 - Mac上若用M1/M2芯片，确保终端是Rosetta模式（右键终端→“显示简介”→勾选“使用Rosetta”），否则
react-native start可能静默崩溃
Metro启动了，但VSCode连不上8081端口
不是所有“连接超时”都怪网络。常见原因是端口被占、防火墙拦截，或Android/iOS设备无法反向代理到宿主机。
- 执行
lsof -i :8081（macOS/Linux）或netstat -ano | findstr :8081（Windows），杀掉占用进程；也可换端口：npx react-native start --port 8082 - Android真机需额外执行
adb reverse tcp:8081 tcp:8081，否则手机访问不到本地Metro；iOS真机不支持该命令，必须用http://localhost:8081替换为宿主机IP（如http://192.168.1.100:8081）并关掉防火墙 - 公司网络或某些安全软件会拦截
localhost:8081，临时关闭防火墙测试；macOS上检查“系统设置→隐私与安全性→防火墙”是否放行Node.js
热重载卡住、白屏、断点不命中
这不是VSCode的问题，而是Metro缓存残留或模块注册不一致导致的“假性超时”。现象是改代码后界面不动，控制台也没报错，像卡死了一样。
- 强制清空Metro缓存：
rm -rf $TMPDIR/metro-* && rm -rf $TMPDIR/haste-map-* && npx react-native start --reset-cache - 检查
index.js里AppRegistry.registerComponent的模块名，和android/app/src/main/java/.../MainActivity.java中getMainComponentName()返回值是否完全一致（包括大小写） - 摇动Android设备调出开发者菜单，确认勾选的是
Enable Hot Reloading，不是Live Reload——后者要整页刷新，延迟更明显
VSCode提示“Cannot connect to Metro”但终端能访问http://localhost:8081
说明VSCode没拿到正确的Metro地址，通常发生在多项目共存、环境变量污染或扩展配置错乱时。
- 删掉项目根目录下
.vscode/launch.json，改用VSCode内置的JavaScript Debug Terminal运行npm start，避免插件解析路径出错 - 检查
~/.bash_profile或~/.zprofile里有没有误设REACT_NATIVE_PACKAGER_HOST=xxx之类覆盖默认host的变量 - VSCode插件“React Native Tools”有已知bug：升级到v1.14+后，若项目含
workspaces或pnpm，会错误读取根目录外的node_modules，降级回v1.13.0可绕过
Metro本身不处理网络超时逻辑，所有“超时”都是客户端（VSCode、ADB、设备WebView）主动放弃连接的结果。真正要盯住的，永远是那条命令行输出：Building and serving bundle...是否出现，以及<a href="https://www.php.cn/link/f33d24234403ab352c4fcaaa86d9aedf">https://www.php.cn/link/f33d24234403ab352c4fcaaa86d9aedf</a>能否在浏览器里直接打开。
