Supabase 本地开发环境连接失败的根源及跨设备调试解决方案

作者：袖梨 2026-07-11

本文详解 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）