在 Server Components 中读取用户会话next-firebase-auth-edge getTokens 使用教程【免费下载链接】next-firebase-auth-edgeNext.js Firebase Authentication for Edge and Node.js runtimes. Compatible with latest Next.js features.项目地址: https://gitcode.com/gh_mirrors/ne/next-firebase-auth-edge在 Next.js 的 Server Components 中读取用户会话是构建现代应用的关键需求而next-firebase-auth-edge提供的getTokens函数正是解决这一问题的利器。它是一个专为 Next.js App Router 设计的 Firebase 认证库能在 Edge 与 Node.js 运行时无缝工作。本文将用最通俗的方式带你完整掌握getTokens的用法从参数配置、代码示例到常见的坑新手也能快速上手。什么是 getTokensServer Components 中的会话读取利器 getTokens是next-firebase-auth-edge提供的核心函数用于提取并校验用户的登录凭证。它只能在 Server Components 或 API Route Handlers 中使用相关源码位于src/next/tokens.ts。它的工作原理很简单从请求的 Cookie 中读取由authMiddleware写入的会话数据然后完成签名校验与 JWT 解码最终返回结构化数据。如果用户未登录或凭证过期则返回null。函数的返回结果包含以下字段字段说明tokenJWT 编码的 ID Token 字符串decodedToken解码后的用户信息对象邮箱、uid 等customToken自定义 Token需在中间件开启enableCustomTokenmetadata中间件getMetadata写入的自定义数据前置准备先配置好 authMiddleware 中间件 ⚙️在调用getTokens之前你需要先通过authMiddleware完成登录/登出与 Cookie 管理。它负责在用户登录时把凭证写入 Cookie并自动刷新过期 Token。在proxy.tsNext.js 14-15 为middleware.ts中配置如下参考官方文档docs/pages/docs/usage/middleware.mdxexport async function proxy(request: NextRequest) { return authMiddleware(request, { loginPath: /api/login, logoutPath: /api/logout, apiKey: 你的-Firebase-Web-API-Key, cookieName: AuthToken, cookieSignatureKeys: [签名密钥至少32字节], serviceAccount: { /* projectId, clientEmail, privateKey */ } }); } 注意apiKey、cookieName、cookieSignatureKeys必须与后面getTokens的配置保持一致否则无法读取到会话。核心用法在 Server Components 中读取用户会话 下面是一个完整示例展示如何在 Server Component 中调用getTokens获取当前登录用户import {getTokens} from next-firebase-auth-edge; import {cookies} from next/headers; import {notFound} from next/navigation; export default async function ServerComponentExample() { // Next.js 15 中 cookies() 返回 Promise必须 await const tokens await getTokens(await cookies(), { apiKey: XXxxXxXXXxXxxxxx_XxxxXxxxxxXxxxXXXxxXxX, cookieName: AuthToken, cookieSignatureKeys: [Key-Should-Be-at-least-32-bytes-in-length], serviceAccount: { projectId: your-firebase-project-id, clientEmail: firebase-adminsdk-xxxproject.iam.gserviceaccount.com, privateKey: -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n } }); if (!tokens) { return notFound(); } const {token, decodedToken, customToken, metadata} tokens; return ( div p用户邮箱{decodedToken.email}/p p用户 uid{decodedToken.uid}/p /div ); }在官方示例项目examples/next-typescript-starter/app/layout.tsx中你可以看到更进阶的用法——在根布局中调用getTokens再把用户信息通过AuthProvider注入到客户端组件实现全局会话共享。⚠️版本差异提醒Next.js 15 起cookies()变为异步必须写await cookies()Next.js 14 中是同步的直接传cookies()即可。getTokens 参数配置详解必填与可选 ️getTokens的第二参数是配置对象合理配置是读取会话成功的关键。必填参数参数名说明apiKeyFirebase Web API Key在 Firebase 控制台项目设置中获取cookieName中间件写入的 Cookie 名称必须与authMiddleware一致cookieSignatureKeys校验 Cookie 签名的轮换密钥数组serviceAccountFirebase 服务账号凭据在 Google Cloud Run 认证环境下可选可选参数参数名说明tenantId多租户项目的租户标识符debug设为true可输出调试日志enableTokenRefreshOnExpiredKidHeader密钥轮换时是否自动刷新 Token 生产环境建议把配置抽离到单独文件如官方示例中的config/server-config.ts通过环境变量注入敏感信息避免硬编码。优雅处理未登录状态返回值判断技巧 getTokens在以下两种情况返回null请求中没有认证 Cookie用户尚未登录凭证已过期或签名校验失败因此读取会话后务必先判空再访问字段。常用处理方式有if (!tokens) { return notFound(); // 返回 404 // 或 redirect(/login) // 重定向到登录页 }这种方式天然适合做页面级访问控制配合中间件的重定向逻辑可以轻松实现未登录用户看不到受保护页面的效果。进阶技巧metadata 与 decodedToken 的高阶玩法 1. 用 metadata 存储业务数据在中间件中配置getMetadata回调可以在登录或刷新凭证时把自定义数据如用户角色写入 Cookie然后在 Server Component 中通过getTokens读取// proxy.ts 中配置 getMetadata: async (tokens) { return {uid: tokens.decodedIdToken.uid, roles: await loadRoles()}; } // Server Component 中读取 const {metadata} await getTokens(await cookies(), authConfig); console.log(metadata.roles);2. 常见 decodedToken 字段decodedToken包含 Firebase ID Token 的标准字段最常用的有uid/sub用户唯一标识email/email_verified邮箱及验证状态name、picture、phone_number用户资料信息firebase.sign_in_provider登录方式密码、Google 等常见问题与排查指南 Q1getTokens 一直返回 null先检查cookieName、apiKey是否与中间件配置一致再确认是否已调用过登录接口写入 Cookie。Q2cookies() 报类型错误Next.js 15 必须使用await cookies()检查你的 Next.js 版本并相应调整。Q3自定义 claims 不生效在中间件中配置dynamicCustomClaimsKeys声明需要动态刷新的 claim 字段。Q4Cookie 太大导致写入失败在中间件中开启enableMultipleCookies: true把会话拆分为多个 CookieFirebase Hosting 除外。总结 ✨getTokens让在 Server Components 中读取用户会话变得异常简单一次调用即可获得校验过的用户身份配合authMiddleware构成完整的认证闭环。掌握了本教程的参数配置、判空处理和进阶技巧你就能在 Next.js 应用中轻松实现服务端鉴权、个性化页面渲染等功能。建议直接参考项目的examples/next-typescript-starter示例结合src/next/tokens.ts源码与docs/pages/docs/usage/server-components.mdx官方文档加深理解快速落地到自己的项目中。【免费下载链接】next-firebase-auth-edgeNext.js Firebase Authentication for Edge and Node.js runtimes. Compatible with latest Next.js features.项目地址: https://gitcode.com/gh_mirrors/ne/next-firebase-auth-edge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
