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
限制
- 僅在任務明確符合上述範圍時使用此技能。
- 不要將輸出視為環境特定驗證、測試或專家審查的替代品。
- 若缺少必要輸入、權限、安全邊界或成功標準,請停止並請求釐清。