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

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

1. 获取开发机的局域网 IPv4 地址

   • macOS/Linux：ipconfig getifaddr en0 或 hostname -I | awk '{print $1}'
   • Windows：ipconfig | findstr "IPv4" → 找到类似 192.168.x.x 的地址（非 127.0.0.1）

2. 更新客户端初始化 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 登录页。若打不开，说明网络层未通，无需继续调试代码。

⚠️ 常见误区总结

完成上述配置后，supabase.from("test").select("*") 将正常返回数据，且 curl 命令与 React Native 客户端行为完全一致——这意味着你已真正打通本地 Supabase 全栈开发闭环，彻底告别云端延迟。