本文详解React Native等移动端项目连接本地Supabase CLI服务时出现“Network request failed”的根本原因——localhost在移动设备上无法解析为宿主机，必须改用局域网IP并配置CORS与网络权限。
本文详解react native等移动端项目连接本地supabase cli服务时出现“network request failed”的根本原因——`localhost`在移动设备上无法解析为宿主机，必须改用局域网ip并配置cors与网络权限。
在使用 Supabase CLI 本地启动开发环境（supabase start）后，服务默认运行于 http://localhost:54321（Studio）、http://localhost:3000（PostgREST API）等端口。该地址对开发机本身有效，但在 React Native（Expo 或 bare workflow）、iOS 模拟器、Android 真机或浏览器开发者工具中直接访问 localhost 会失败——因为 localhost 指向的是设备自身（如手机），而非运行 Supabase 的开发电脑。
✅ 正确配置：替换为局域网 IP 并验证可达性
-
获取开发机局域网 IP
- macOS/Linux：ipconfig getifaddr en0（Wi-Fi）或 hostname -I
- Windows：ipconfig | findstr "IPv4"，取形如 192.168.x.x 的地址（非 127.0.0.1 或 ::1）
修改客户端初始化代码
将 http://localhost:54321 替换为实际 IP，并使用 PostgREST API 端口 3000（非 Studio 端口 54321）：
// ✅ 正确：指向 PostgREST API（默认端口 3000）
const supabaseUrl = 'http://192.168.1.100:3000'; // 替换为你的真实局域网IP
const supabaseAnonKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
auth: {
storage: new LargeSecureStore(),
autoRefreshToken: true,
persistSession: true,
detectSessionInUrl: false,
},
});⚠️ 注意：supabase start 启动后，API 服务实际运行在 :3000（PostgREST），而 :54321 是 Studio（Web 控制台）端口。客户端必须调用 :3000 才能访问数据库接口。
? 必须配置 CORS（跨域资源共享）
Supabase CLI 默认仅允许 localhost 访问 API。若从手机或模拟器（IP 如 192.168.1.105）发起请求，需显式添加允许来源：
# 在项目根目录执行（需已运行 supabase start） supabase db remote set --url "http://192.168.1.100:54321" # 可选，用于链接远程配置 # 更关键的是配置 PostgREST 的 CORS： supabase config set --env POSTGREST_DB_SCHEMA=public supabase config set --env POSTGREST_SERVER_CORS_ALLOWED_ORIGINS="http://localhost:3000,http://192.168.1.100:3000,exp://192.168.1.100:19000"
或者，在 .supabase/config.toml 中手动添加（重启 supabase start 生效）：
[api] cors_allowed_origins = "http://localhost:3000,http://192.168.1.100:3000,exp://192.168.1.100:19000"
? 移动端专项适配（Expo / React Native）
- Expo 开发者工具：确保 exp://192.168.1.100:19000（或 exp+your-app-scheme://...）已加入 CORS_ALLOWED_ORIGINS
- Android 真机调试：关闭手机 Wi-Fi 隔离（部分路由器默认开启），确保手机与电脑在同一局域网
- iOS 模拟器：localhost 在模拟器中可映射到 Mac，但真机仍需 IP；建议统一使用 IP 方案
- HTTPS 警告：若使用自签名证书或 HTTP，Android 9+ 需在 android/app/src/main/res/xml/network_security_config.xml 中显式允许明文流量（仅限开发）
? 验证连通性（终端快速检查）
# 从手机浏览器或 curl（在另一台设备上）测试 API 是否可达 curl -H "apikey: $ANON_KEY" "http://192.168.1.100:3000/rest/v1/test" # 若返回 JSON 数据，则网络与 CORS 均正常；否则检查防火墙、Docker 网络或路由器设置
✅ 总结：三步定位与修复
| 步骤 | 检查项 | 正确做法 |
|---|---|---|
| 1. 地址解析 | 客户端是否用 localhost？ | ✅ 改为开发机局域网 IP + :3000 |
| 2. 端口匹配 | 是否误用 Studio 端口 54321？ | ✅ API 必须用 :3000（PostgREST） |
| 3. 权限控制 | CORS 是否放行设备 IP？ | ✅ 在 config.toml 或 CLI 中配置 cors_allowed_origins |
完成上述配置后，重启 supabase start 和前端开发服务器，即可实现 React Native、Flutter 或任意跨设备客户端对本地 Supabase 栈的无缝调试——真正告别云端延迟，享受毫秒级响应的全栈开发体验。
