Supabase本地开发连接失败原因及跨设备调试方案

本文详解 React Native（Expo）等移动端项目连接本地 Supabase CLI 服务时出现 “Network request failed” 的根本原因——localhost 在移动设备上无法解析为宿主机，必须改用局域网 IP 并配置 CORS、Docker 网络与客户端初始化参数。

用 React Native（Expo）开发时，本地 Supabase 环境跑得飞起，可一上手机就报错“Network request failed”，这事儿简直能把人整崩溃。其实，问题出在一个很基础的认知偏差上：localhost 这玩意儿，在手机端指的是手机自己，而不是你的开发电脑。

Supabase CLI 启动后，服务默认绑定在 http://localhost:54321（Studio）和 http://localhost:54321/rest/v1/（PostgREST API）。在浏览器或 Node.js 脚本里，这没问题，因为 localhost 指向的就是当前机器。但手机一接入，它就去访问自己的 loopback 接口，结果自然是一无所获。

✅ 正确做法：用局域网 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，端口保持不变：

   // ✅ 正确示例（假设开发机局域网 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 输出的 URL 动态调整。

• 步骤 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("*") 应该就能正常返回数据了。这意味着你已经打通了本地 Supabase 全栈开发闭环，彻底告别了云端延迟的烦恼。