跳到内容
光环标志
光环基地

Next.js 应用程序路由器和 SSR 指南

将 Aurabase 集成到带有服务器组件、服务器操作、中间件和安全会话的 Next.js 15/16 App Router 应用程序中的分步架构指南。

操作指南10分钟 读取级别 中间修改于 2026年8月19日

该页面已自动翻译。英文版具有权威性。

Aurabase SSR 模型#

在现代服务器端渲染的应用程序中,用户的身份验证状态无法存储在浏览器的 localStorage 中(服务器无法访问)。 Aurabase 自动同步安全 HTTP cookie 中的会话。

完全查询隔离

createServerClient 在内存中没有共享状态。每个服务器请求都会实例化一个连接到请求的 HTTP 标头的隔离客户端,保证用户之间的绝对紧密性(会话泄漏的风险为零)。

应用路由器的三大支柱#

proxy.tstypescript
import { createServerClient } from '@aurabase/aurabase-js/ssr'
import { NextResponse, type NextRequest } from 'next/server'

// Next.js 16:该文件是“proxy.ts”,函数名为“proxy”。
// Next.js 15:将文件命名为“middleware.ts”,将函数命名为“middleware”。
export async function proxy(request: NextRequest) {
  const response = NextResponse.next({ request })
  const aura = createServerClient(
    process.env.NEXT_PUBLIC_AURABASE_URL!,
    process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
    {
      cookies: {
        getAll() { return request.cookies.getAll() },
        setAll(cookies) {
          cookies.forEach(({ name, value, options }) => {
            request.cookies.set(name, value)
            response.cookies.set(name, value, options)
          })
        },
      },
    })

  const { data: user } = await aura.auth.getUser()
  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return response
}

多分块的自动管理#

Web 浏览器将 cookie 的大小限制为大约 4 KB。当 JWT 令牌或用户元数据超过此限制时,@aurabase/aurabase-js/ssr 模块会自动将负载拆分为多个编号的 cookie:

  • aura-<scope>-auth.0(前 3600 字节)
  • aura-<scope>-auth.1(会议剩余时间)

读取后,服务器忠实地重新组装块,以恢复状态,而不会丢失任何数据或会话中断。

生产黄金法则#

HttpOnly 和 SameSite 属性

刷新令牌 cookie 决不应该暴露给客户端 JavaScript,以防止 XSS 攻击。

Role Key 服务严格服务器

切勿使用“use client”指令将 AURABASE_SERVICE_ROLE_KEY 传递到 createBrowserClient 或组件中。

中间件刷新

在代理中调用 getUser()(Next.js 15 上的middleware.ts):它会在令牌过期之前更新令牌,并询问服务器用户是谁。切勿使用 getSession() 授权服务器请求:在服务器上,它仅读取浏览器可以伪造的 cookie。

为了走得更远#