如何捕获/处理Supabase OAuth回调URL中的错误？

问题场景 #

使用Supabase OAuth Provider和OAuth UI结合Next.js App Dir开发登录功能时，遇到以下用户体验问题：当用户尝试用Github等第三方服务商登录，但该邮箱已通过Google创建过账号，Supabase回调URL会携带错误参数，但页面返回200状态码，前端无法默认捕获该错误，导致用户操作后无任何反馈，体验极差。

错误回调示例：

http://localhost:3000/?error=server_error&error_description=Multiple+accounts+with+the+same+email+address+in+the+same+linking+domain+detected

解决方案 #

通过以下方式实现错误捕获与用户提示：

• 使用Next.js的useSearchParams解析回调URL中的错误参数
• 在组件加载时检查错误并展示对应提示
• 完善onAuthStateChange事件的错误处理逻辑，覆盖更多登录异常场景

修改后的代码示例 #

//...
import { useSearchParams } from 'next/navigation';

const AuthModal = () => {
  const router = useRouter();
  const supabase = createClientComponentClient<Database>();
  const searchParams = useSearchParams();
  
  // Zustand custom hook
  const { isOpen, onClose, view } = useAuthModal();
  // 提取URL中的错误参数
  const error = searchParams.get('error');
  const errorDescription = searchParams.get('error_description');

  useEffect(() => {
    // 处理URL中的错误信息
    if (error && errorDescription) {
      // 替换为你的项目提示组件（如Toast、Alert）
      alert(decodeURIComponent(errorDescription));
      // 清除URL中的错误参数，避免刷新页面重复提示
      router.replace('/', undefined, { shallow: true });
    }

    supabase.auth.onAuthStateChange(async(event, session) => {
      if(event === "SIGNED_IN") {
        router.refresh();
        onClose();
      }
      // 处理Auth状态变更中的错误场景
      if(event === "ERROR") {
        alert(session?.error?.message || '登录失败，请稍后重试');
      }
    })
  }, [router, onClose, supabase.auth, error, errorDescription]);


  function onChange(open: boolean) {
    if(!open) {
      onClose();
    }
  }

  return (
    <Modal 
      title={view === "sign_in" ? "Welcome back" : "Sign up"}
      description={view === "sign_in" 
        ? "Login to your account" 
        : "Or sign in with your favorite account"
      }
      isOpen={isOpen}
      onChange={onChange}   
    >
      {/* 在Auth组件上方展示错误提示 */}
      {error && (
        <div style={{color: 'red', marginBottom: '16px', padding: '8px', borderRadius: '4px', backgroundColor: '#ffebee'}}>
          {decodeURIComponent(errorDescription || '登录出错')}
        </div>
      )}
      <Auth 
        theme="dark"
        magicLink
        providers={["github", "google"]}
        socialLayout="vertical"
        supabaseClient={supabase} 
        view={view}
        appearance={{
          theme: ThemeSupa,
          variables: {
            default: {
              colors: {
                brand: "#404040",
                brandAccent: "#10b981"
              }
            }
          } 
        }}
      />
    </Modal>
  )
}
export default AuthModal;

关键说明 #

• useSearchParams是Next.js App Dir中获取URL参数的API，需从next/navigation导入
• 错误描述参数需用decodeURIComponent解码，还原空格等特殊字符
• 展示错误后通过router.replace清除URL错误参数，避免用户刷新页面重复触发提示
• 补充onAuthStateChange的ERROR事件处理，覆盖登录过程中出现的其他异常情况

内容的提问来源于stack exchange，提问作者ShueiYang