技能介绍

要解决什么问题

在 Next.js App Router 里接 Supabase Auth，难点往往不在「能不能登录」，而在 服务端与客户端边界：中间件要不要刷新 cookie、Server Component 里该读什么、OAuth 回调如何把 code 换成会话，以及如何避免把 token 暴露给浏览器。本技能面向已经选定 Supabase 后端的团队，把 @supabase/ssr 的推荐用法收敛成可执行的决策树。

技能如何帮你落地

技能按场景拆成三类模式，而不是堆 API 清单：

Supabase 客户端配置：为中间件、Server Components、Client Components 分别创建配置正确的客户端，避免混用导致会话不同步。
认证中间件：在 middleware 里保护受保护路由，并在请求链路上刷新会话，而不是只在页面里临时判断。
认证回调路由：实现 OAuth 回调，用授权码兑换会话并写回基于 cookie 的会话流程。

核心原则包括：非必要不向客户端暴露认证 token；认证操作尽可能走 Server Actions；理解 cookie 会话在 App Router 中的完整路径。能力标签覆盖 nextjs-auth、auth-middleware、auth-callback 等，与 nextjs-app-router、supabase-backend 技能衔接更顺。

边界与反模式

技能明确反对几种常见踩坑：在 Server Components 中调用 getSession、客户端认证状态没有订阅/监听、以及手动把 token 存进 localStorage。若你的栈不是 App Router，或认证完全在纯客户端 SPA 里完成，本技能的中间件与 SSR 假设需要对齐后再用。

截图预览

使用场景

新建 App Router 项目后，要在 `middleware` 里拦截 `/dashboard` 等路径，并在每次请求时刷新 Supabase 的 cookie 会话。
接入 GitHub 或 Google OAuth 后，需要实现 callback 路由，把 redirect 带回的 `code` 兑换成可写回的会话。
页面同时有 Server Component 与 Client Component，需要为中间件、服务端、浏览器各建一套正确的 Supabase 客户端，避免登录态不同步。
要把登录、登出从客户端 fetch 改成 Server Actions，同时避免在 RSC 里误用 `getSession` 读会话。

适合人员

用 Next.js App Router 与 Supabase 做 SaaS 的全栈工程师，希望受保护路由在 middleware 完成校验且 token 尽量不暴露给客户端。
正在从旧版 Supabase Auth Helpers 迁移到 `@supabase/ssr` 的维护者，需要对齐中间件、RSC 与 Client 三层的会话读取方式。
负责 B 端管理后台的 Next.js 开发者，要把 OAuth 回调与会话写入流程按官方 SSR 模式一次性接对。
排查「本地已登录但服务端组件仍判未登录」问题的工程师，需要对照中间件刷新与客户端配置的反模式清单。