本文详解 React Native（Expo）等移动端项目连接本地 Supabase CLI 服务时出现 “Network request failed” 的根本原因——localhost 在移动设备上无法解析为宿主机，必须改用局域网 IP 并配置 CORS、Docker 网络与客户端初始化参数。
本文详解 react native（expo）等移动端项目连接本地 supabase cli 服务时出现 “network request failed” 的根本原因——`localhost` 在移动设备上无法解析为宿主机，必须改用局域网 ip 并配置 cors、docker 网络与客户端初始化参数。
在使用 Supabase CLI 启动本地全栈环境（supabase start）后，服务默认绑定在 http://localhost:54321（Studio）、http://localhost:54321/rest/v1/（PostgREST API）等地址。这一配置对本机浏览器或 Node.js 进程完全有效，但当通过 Expo 开发的 React Native 应用在手机或模拟器中运行时，localhost 指向的是设备自身（即手机的 loopback 接口），而非你的开发电脑——这正是 TypeError: Network request failed 的根本原因。
✅ 正确做法：使用局域网 IP 替代 localhost
-
获取开发机的局域网 IPv4 地址
- macOS/Linux：ipconfig getifaddr en0 或 hostname -I | awk '{print $1}'
- Windows：ipconfig | findstr "IPv4" → 找到类似 192.168.x.x 的地址（非 127.0.0.1）
-
更新客户端初始化 URL
将 http://localhost:54321 替换为该 IP，并确保端口一致（默认 54321）：// ✅ 正确示例（假设开发机局域网 IP 是 192.168.1.100） const supabaseUrl = 'http://192.168.1.100:54321'; const supabaseAnonKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; export const supabase = createClient(supabaseUrl, supabaseAnonKey, { auth: { storage: new LargeSecureStore(), autoRefreshToken: true, persistSession: true, detectSessionInUrl: false, }, // ⚠️ 关键：禁用 fetch 超时（移动端网络波动更敏感） global: { headers: { 'X-Client-Info': 'react-native-expo/1.0.0', } } });
? 必须同步配置的服务端项
仅改 URL 不够！Supabase CLI 默认只允许 localhost 和 127.0.0.1 的 CORS 请求。需手动启用局域网访问：
-
步骤 1：修改 .supabase/config.toml
在项目根目录的 .supabase/config.toml 中，找到 [api] 区块，添加或修改 cors_allowed_origins：[api] cors_allowed_origins = ["http://localhost:54321", "http://192.168.1.100:54321", "exp://192.168.1.100:19000"]
? exp://192.168.1.100:19000 是 Expo 开发服务器地址（根据 expo start 输出的地址动态调整）。
-
步骤 2：重启本地服务
supabase stop && supabase start
否则新配置不会生效。
步骤 3：验证 Docker 网络可达性（Windows/macOS）
确保开发机防火墙未拦截 54321 端口（macOS：系统设置 → 隐私与安全性 → 防火墙；Windows：高级安全 Windows Defender 防火墙 → 入站规则）。
? Expo 特别注意事项
- 若使用 npx expo start --tunnel，需在 app.config.js 中显式配置 hostType: 'tunnel'，此时应使用隧道 URL（如 https://xxx.ngrok.io），而非局域网 IP；
- 真机调试时，手机与开发机必须在同一 Wi-Fi 网络下；
- Android 模拟器默认无法访问宿主机 192.168.x.x，建议改用 10.0.2.2（VirtualBox/Genymotion）或 127.0.0.1（部分新版模拟器支持 host-only 网络）。
✅ 验证是否成功
在手机端执行请求前，先用手机浏览器访问 http://192.168.1.100:54321 —— 应能打开 Supabase Studio 登录页。若打不开，说明网络层未通，无需继续调试代码。
⚠️ 常见误区总结
| 错误做法 | 后果 | 正确方案 |
|---|---|---|
| 仍用 localhost 初始化客户端 | 请求发往手机自身，无服务响应 | 改用开发机局域网 IP |
| 未修改 config.toml 的 CORS 配置 | 请求被 PostgREST 拒绝，返回 403 Forbidden 或空响应 | 显式添加 cors_allowed_origins |
| 修改后未执行 supabase stop && supabase start | 配置不生效，问题依旧 | 必须重启服务 |
| 使用 https:// 协议访问 HTTP 服务 | 混合内容被浏览器拦截 | 保持 http://（本地开发无需 HTTPS） |
完成上述配置后，supabase.from("test").select("*") 将正常返回数据，且 curl 命令与 React Native 客户端行为完全一致——这意味着你已真正打通本地 Supabase 全栈开发闭环，彻底告别云端延迟。
