Next.js + Supabase Auth
选择性阅读规则
从以下文档开始:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
然后仅加载与用户实际任务相匹配的继承文档、脚本、资产或示例。
Supabase Auth 与 Next.js App Router 的专家级集成
能力
- nextjs-auth
- supabase-auth-nextjs
- auth-middleware
- auth-callback
前提条件
- 所需技能:nextjs-app-router,supabase-backend
模式
Supabase 客户端设置
为不同上下文创建正确配置的 Supabase 客户端
何时使用:在 Next.js 项目中设置认证
// lib/supabase/client.ts (浏览器客户端)
'use client'
import { createBrowserClient } from '@supabase/ssr'
export function createClient() {
return createBrowserClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)
}
// lib/supabase/server.ts (服务器客户端)
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
export async function createClient() {
const cookieStore = await cookies()
return createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
cookies: {
getAll() {
return cookieStore.getAll()
},
setAll(cookiesToSet) {
cookiesToSet.forEach(({ name, value, options }) => {
cookieStore.set(name, value, options)
})
},
},
}
)
}
认证中间件
在中间件中保护路由并刷新会话
何时使用:需要路由保护或会话刷新
// middleware.ts
import { createServerClient } from '@supabase/ssr'
import { NextResponse, type NextRequest } from 'next/server'
export async function middleware(request: NextRequest) {
let response = NextResponse.next({ request })
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
cookies: {
getAll() {
return request.cookies.getAll()
},
setAll(cookiesToSet) {
cookiesToSet.forEach(({ name, value, options }) => {
response.cookies.set(name, value, options)
})
},
},
}
)
// 如果会话过期则刷新
const { data: { user } } = await supabase.auth.getUser()
// 保护仪表盘路由
if (request.nextUrl.pathname.startsWith('/dashboard') && !user) {
return NextResponse.redirect(new URL('/login', request.url))
}
return response
}
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}
认证回调路由
处理 OAuth 回调并将授权码交换为会话
何时使用:使用 OAuth 提供商(Google, GitHub 等)
// app/auth/callback/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'
export async function GET(request: Request) {
const { searchParams, origin } = new URL(request.url)
const code = searchParams.get('code')
const next = searchParams.get('next') ?? '/'
if (code) {
const supabase = await createClient()
const { error } = await supabase.auth.exchangeCodeForSession(code)
if (!error) {
return NextResponse.redirect(`${origin}${next}`)
}
}
return NextResponse.redirect(`${origin}/auth/error`)
}
服务器操作认证
在服务器操作中处理认证操作
何时使用:从服务器组件进行登录、注销或注册
// app/actions/auth.ts
'use server'
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import { revalidatePath } from 'next/cache'
export async function signIn(formData: FormData) {
const supabase = await createClient()
const { error } = await supabase.auth.signInWithPassword({
email: formData.get('email') as string,
password: formData.get('password') as string,
})
if (error) {
return { error: error.message }
}
revalidatePath('/', 'layout')
redirect('/dashboard')
}
export async function signOut() {
const supabase = await createClient()
await supabase.auth.signOut()
revalidatePath('/', 'layout')
redirect('/')
}
在服务器组件中获取用户
在服务器组件中访问已认证用户
何时使用:服务器端渲染用户特定内容
// app/dashboard/page.tsx
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
export default async function DashboardPage() {
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) {
redirect('/login')
}
return (
<div>
<h1>欢迎,{user.email}</h1>
</div>
)
}
验证检查
使用 getSession() 进行认证检查
严重级别:错误
消息:getSession() 不会验证 JWT。对于安全的认证检查,请使用 getUser()。
修复措施:将 getSession() 替换为 getUser() 以进行安全关键检查
缺少回调路由的 OAuth
严重级别:错误
消息:使用了 OAuth 但缺少 app/auth/callback/route.ts 回调路由
修复措施:创建 app/auth/callback/route.ts 以处理 OAuth 重定向
在服务器上下文中使用浏览器客户端
严重级别:错误
消息:在服务器上下文中使用了浏览器客户端。请改用 createServerClient。
修复措施:从 @supabase/ssr 导入并使用 createServerClient
缺少中间件的受保护路由
严重级别:警告
消息:未找到 middleware.ts。考虑添加中间件进行路由保护。
修复措施:创建 middleware.ts 以保护路由并刷新会话
硬编码的认证重定向 URL
严重级别:警告
消息:硬编码了 localhost 重定向。为环境灵活性请使用 origin。
修复措施:使用 window.location.origin 或 process.env.NEXT_PUBLIC_SITE_URL
无错误处理的认证调用
严重级别:警告
消息:认证操作没有进行错误处理。请始终检查错误。
修复措施:解构 { data, error } 并处理错误情况
无重新验证的认证操作
严重级别:警告
消息:认证操作没有 revalidatePath。缓存可能显示过时的认证状态。
修复措施:在认证操作后添加 revalidatePath('/', 'layout')
仅客户端的路由保护
严重级别:警告
消息:客户端路由保护会导致内容闪现。请使用中间件。
修复措施:将保护移至 middleware.ts 以获得更好的用户体验
协作
委派触发器
- database|rls|queries|tables -> supabase-backend (认证需要数据库层)
- route|page|component|layout -> nextjs-app-router (认证需要 Next.js 模式)
- deploy|production|vercel -> vercel-deployment (认证需要部署配置)
- ui|form|button|design -> frontend (认证需要 UI 组件)
完整认证栈
技能:nextjs-supabase-auth, supabase-backend, nextjs-app-router, vercel-deployment
工作流:
1. 数据库设置 (supabase-backend)
2. 认证实现 (nextjs-supabase-auth)
3. 路由保护 (nextjs-app-router)
4. 部署配置 (vercel-deployment)
受保护的 SaaS
技能:nextjs-supabase-auth, stripe-integration, supabase-backend
工作流:
1. 用户认证 (nextjs-supabase-auth)
2. 客户同步 (stripe-integration)
3. 订阅门控 (supabase-backend)
相关技能
与以下技能配合良好:nextjs-app-router, supabase-backend
何时使用
- 用户提到或暗示:supabase auth next
- 用户提到或暗示:authentication next.js
- 用户提到或暗示:login supabase
- 用户提到或暗示:auth middleware
- 用户提到或暗示:protected route
- 用户提到或暗示:auth callback
- 用户提到或暗示:session management
限制
- 仅当任务明确匹配上述范围时,才使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少所需的输入、权限、安全边界或成功标准,请停止并寻求澄清。