本文详解 React Native（尤其 Expo 环境）无法访问本地 Supabase 实例的根本原因，指出 localhost 在移动设备上的解析失效问题，并提供基于局域网 IP 的正确配置方案、安全注意事项及完整可运行代码示例。
本文详解 react native（尤其 expo 环境）无法访问本地 supabase 实例的根本原因，指出 `localhost` 在移动设备上的解析失效问题，并提供基于局域网 ip 的正确配置方案、安全注意事项及完整可运行代码示例。
在 React Native（特别是使用 Expo 开发模式）中连接本地运行的 Supabase CLI 开发服务时，出现 TypeError: Network request failed 是一个高频但易被误解的问题。表面上看是网络请求失败，实则并非代码逻辑或 Supabase 配置错误，而是网络可达性层面的根本限制：localhost（即 127.0.0.1）在 Android/iOS 设备上始终指向设备自身，而非开发机——这意味着你的手机或模拟器根本无法通过 http://localhost:54321 访问你电脑上运行的 Supabase 本地服务。
✅ 正确做法是：将 localhost 替换为开发机在局域网中的真实 IPv4 地址（例如 http://192.168.1.23:54321），并确保网络互通。
? 操作步骤
-
获取开发机局域网 IP
- macOS/Linux：终端执行 ipconfig getifaddr en0（Wi-Fi）或 hostname -I（Linux）
- Windows：命令提示符运行 ipconfig，查找“无线局域网适配器 WLAN”下的 IPv4 地址（如 192.168.1.23）
-
验证网络连通性
在手机浏览器中直接访问 http://192.168.1.23:54321/health，若返回 {"status":"success"}，说明网络通畅；否则需检查：- 开发机防火墙是否放行 54321 端口；
- 手机与开发机是否处于同一 Wi-Fi 网络；
- Supabase CLI 是否以 --host 0.0.0.0 启动（默认仅监听 127.0.0.1）：
supabase start --host 0.0.0.0
-
更新 Supabase 客户端配置
// ✅ 正确：使用局域网 IP（替换为你的实际 IP） const supabaseUrl = 'http://192.168.1.23:54321'; const supabaseAnonKey = 'your-anon-key-here'; export const supabase = createClient(supabaseUrl, supabaseAnonKey, { auth: { storage: new LargeSecureStore(), autoRefreshToken: true, persistSession: true, detectSessionInUrl: false, }, }); -
（重要）Android/iOS 网络权限补充
-
Android：确保 android/app/src/main/AndroidManifest.xml 中已启用明文流量（仅限开发环境）：
<application android:usesCleartextTraffic="true" ... >
-
iOS：需在 ios/YourApp/Info.plist 中添加 App Transport Security 配置（开发阶段允许 HTTP）：
<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict>
-
Android：确保 android/app/src/main/AndroidManifest.xml 中已启用明文流量（仅限开发环境）：
⚠️ 注意事项与最佳实践
- ❌ 禁止在生产环境使用局域网 IP 或 http:// 协议：Supabase 要求 HTTPS + 公网域名，本地调试完成后务必切换回托管环境 URL（如 https://xxx.supabase.co）。
- ? RLS 策略仍需配置：即使网络连通，若未启用对应表的行级安全策略（如 USING (true)），查询仍会返回空数组或权限错误——请通过 Supabase Dashboard → Table Editor → RLS 启用读取策略。
- ? 调试建议：使用 curl 或 Postman 直接测试该 IP+端口，排除客户端干扰；同时检查 supabase logs 查看服务端是否收到请求。
✅ 最终验证示例
const checkConnection = async () => {
try {
const { data, error } = await supabase.from('test').select('*');
if (error) throw error;
console.log('✅ Local Supabase query succeeded:', data);
} catch (err) {
console.error('❌ Query failed:', err);
}
};只要 IP 正确、端口开放、防火墙放行、RLS 合理，即可稳定访问本地 Supabase 实例，大幅提升本地迭代效率。记住：localhost 是开发机的“自我指代”，而移动设备需要的是它的“局域网门牌号”。
