nextjs-supabase-auth

Next.js + Supabase Auth 认证集成

技能概述

nextjs-supabase-auth 是一个专精于在 Next.js App Router 中集成 Supabase 身份验证的专家级 AI 技能，帮助你处理服务端/客户端边界、中间件认证、Server Components 和 Server Actions 中的登录逻辑。

适用场景

Next.js App Router 项目需要用户登录功能 — 当你使用 Next.js 13+ 的 App Router 架构，希望集成 Supabase 作为认证提供商时

需要服务端渲染的受保护路由 — 当你的应用需要根据用户登录状态渲染不同内容，且必须在服务端完成验证时

处理 OAuth 登录和会话管理 — 当你需要实现第三方登录（如 Google、GitHub），并确保会话在服务端正确刷新和维护时

核心功能

Supabase SSR 客户端配置 — 基于不同运行环境（服务端组件、客户端组件、路由处理器、Server Actions）创建正确的 Supabase 客户端实例，确保 @supabase/ssr 包的正确使用

认证中间件与路由保护 — 在 Next.js 中间件中实现自动会话刷新和路由保护，确保未登录用户无法访问受保护页面，同时避免 Token 暴露到客户端

OAuth 回调与 Server Actions 登录 — 处理 OAuth 授权码换取会话的完整流程，以及通过 Server Actions 实现的服务端登录/登出操作

常见问题

Next.js App Router 如何集成 Supabase Auth？

使用 @supabase/ssr 包，根据上下文创建不同的客户端实例。在 Server Components 中使用 createServerClient，在 Route Handlers 中传入 cookies，在客户端使用 createBrowserClient。这个技能会指导你正确区分各种场景的客户端创建方式。

Supabase 会话刷新在 Next.js 中如何自动处理？

在 Next.js 中间件（middleware.ts）中调用 supabase.auth.getSession() 会自动刷新过期的会话。这个技能强调将刷新逻辑放在中间件而非组件中，确保所有受保护路由的请求都能自动更新 Cookie 中的会话。

为什么不能在 Server Components 中直接使用 getSession？

Server Components 是渲染时执行的，而 getSession 需要读取 Cookie 中的会话信息。正确做法是通过 middleware 提前处理会话刷新，或使用辅助函数从 Cookie 中读取会话传递给组件。这个技能会避免常见的服务端认证反模式。