Twilioapp-admin/SUPABASE_FIXES.md

Supabase 多实例问题修复

问题描述

在开发环境中遇到了以下警告：

Multiple GoTrueClient instances detected in the same browser context. It is not an error, but this should be avoided as it may produce undefined behavior when used concurrently under the same storage key.

这个问题通常发生在：

1. React 热重载导致多个 Supabase 客户端实例被创建
2. 不同的模块重复导入和创建 Supabase 客户端
3. 没有使用单例模式管理客户端实例

解决方案

1. 实现单例模式 (lib/supabase.ts)

// 全局变量声明，用于在开发环境中避免多实例
declare global {
  var __supabase: any;
  var __supabaseAdmin: any;
}

// 创建或获取 Supabase 客户端实例（使用全局变量避免热重载问题）
const getSupabaseClient = () => {
  if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
    if (!global.__supabase) {
      global.__supabase = createClient(/* 配置 */);
    }
    return global.__supabase;
  }
  
  // 生产环境或服务端渲染时的单例
  if (!global.__supabase) {
    global.__supabase = createClient(/* 配置 */);
  }
  return global.__supabase;
};

2. 路由器节流问题修复 (pages/_app.tsx)

添加了防抖机制来避免频繁的路由跳转：

const navigateWithDebounce = (path: string) => {
  if (navigationInProgress) return;
  
  setNavigationInProgress(true);
  
  if (navigationTimeoutRef.current) {
    clearTimeout(navigationTimeoutRef.current);
  }
  
  navigationTimeoutRef.current = setTimeout(() => {
    router.push(path).finally(() => {
      setNavigationInProgress(false);
    });
  }, 100);
};

修复内容

lib/supabase.ts

• ✅ 实现了真正的单例模式
• ✅ 使用全局变量在开发环境中避免热重载问题
• ✅ 为生产环境和开发环境分别处理客户端创建
• ✅ 明确指定存储键 storageKey: 'supabase-auth-token'

pages/_app.tsx

• ✅ 添加了路由跳转的防抖机制
• ✅ 防止并发路由操作
• ✅ 正确清理定时器

测试步骤

1. 启动开发服务器：npm run dev
2. 打开浏览器控制台
3. 验证不再显示多实例警告
4. 测试用户认证流程
5. 确认路由跳转正常工作

注意事项

1. 开发环境：使用全局变量确保只有一个客户端实例
2. 生产环境：单例模式确保性能和一致性
3. 热重载：修复后热重载不会创建多个实例
4. 路由跳转：防抖机制避免浏览器节流警告

相关文件

• lib/supabase.ts - Supabase 客户端配置
• pages/_app.tsx - 应用程序主入口
• utils/useClientMount.ts - 客户端挂载检测
• components/ErrorBoundary.tsx - 错误边界

效果

修复后的应用程序：

• ✅ 不再有 Supabase 多实例警告
• ✅ 不再有路由器节流警告
• ✅ 用户认证流程正常
• ✅ 热重载工作正常
• ✅ 性能得到改善