next-firebase-auth-edge API 速查手册getFirebaseAuth 服务端方法详解【免费下载链接】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-edgeNext.js 开发者接入 Firebase 认证时最头疼的往往是 Edge Runtime 与 Node.js Runtime 的兼容问题。next-firebase-auth-edge正是为彻底解决这一痛点而生的开源库而getFirebaseAuth则是它最核心的服务端入口。本文面向新手与普通用户用最简洁的方式梳理 getFirebaseAuth 的初始化方式、全部服务端方法、典型使用场景与常见错误处理帮你快速掌握 Next.js Firebase 认证服务端开发。next-firebase-auth-edge 是什么一句话概括这是一个让你在 Next.js 的 App Router、Server Components、Middleware 等最新特性中无缝使用 Firebase Authentication 的认证库。官方 firebase-admin 依赖 Node.js 内置 crypto 库无法在 Edge Runtime 中运行而 next-firebase-auth-edge 通过 Web Crypto API 实现了自定义 Token 的生成与校验完美兼容 Edge 与 Node.js 双运行时。getFirebaseAuth 就是库对外的服务端认证入口导出位置在 src/index.ts完整实现位于 src/auth/index.ts。调用一次即可获得一整套完整的服务端认证方法集合Auth 对象。getFirebaseAuth 初始化两种调用方式方式一配置对象推荐新版推荐使用 FirebaseAuthOptions 配置对象代码更清晰import { getFirebaseAuth } from next-firebase-auth-edge; const auth getFirebaseAuth({ apiKey: process.env.FIREBASE_API_KEY!, serviceAccount: { projectId: process.env.FIREBASE_PROJECT_ID!, clientEmail: process.env.FIREBASE_ADMIN_CLIENT_EMAIL!, privateKey: process.env.FIREBASE_ADMIN_PRIVATE_KEY.replace(/\\n/g, \n)! }, tenantId: undefined, enableCustomToken: true });参数说明apiKey必填Firebase Web API KeyserviceAccount可选服务账号凭证不传则自动使用应用默认凭证tenantId可选多租户隔离支持enableCustomToken可选是否在 Token 刷新时附带自定义 Token真实项目中的完整配置可参考 config/server-config.ts。方式二旧版参数形式已弃用getFirebaseAuth(serviceAccount, apiKey, tenantId);这种写法目前依然可用但源码中已标记为 deprecated建议新项目统一迁移到配置对象写法。getFirebaseAuth 服务端方法速查表拿到 Auth 对象后你可以直接调用以下 14 个服务端方法方法作用典型场景verifyIdToken校验并解码 ID TokenAPI 路由、Server Action 鉴权verifyAndRefreshExpiredIdToken校验失败时自动刷新 TokenMiddleware 会话无感续期createSessionCookie创建 Session Cookie传统会话登录模式createCustomToken基于 uid 生成自定义 Token自定义认证流程getCustomIdAndRefreshTokens用 ID Token 换取新的 Token 对Token 交换迁移getUser / getUserByEmail按 UID 或邮箱查询用户用户信息展示listUsers分页列出全部用户管理后台createUser / createAnonymousUser创建正式用户 / 匿名账号注册、匿名体验updateUser / deleteUser更新 / 删除用户用户资料管理setCustomUserClaims设置自定义声明角色权限控制下面挑重点方法逐一说明。认证核心方法详解verifyIdToken最常用的 ID Token 校验校验并解码 ID Token返回 DecodedIdToken 对象包含 uid、email、exp、firebase 等字段const decoded await auth.verifyIdToken(idToken, { checkRevoked: true }); console.log(decoded.uid, decoded.email);开启 checkRevoked 后还会额外检查 Token 是否被吊销、用户是否被禁用安全性更高。verifyAndRefreshExpiredIdToken过期自动刷新这是 Middleware 场景的利器当 ID Token 过期时自动使用 refreshToken 换取全新 Token 对并触发 onTokenRefresh 回调实现用户无感续期无需重新登录。createSessionCookie创建会话 Cookieconst sessionCookie await auth.createSessionCookie(idToken, 7 * 24 * 60 * 60 * 1000);第二个参数是过期时间毫秒适合需要传统会话 Cookie 的登录模式。createCustomToken生成自定义 Token基于 uid 和自定义声明生成 Custom Token可配合 Firebase Client SDK 的 signInWithCustomToken 方法完成自定义认证闭环。用户管理方法详解查询用户getUser、getUserByEmail、listUsers三个方法都返回 UserRecord 对象类型定义见 src/auth/user-record.ts包含 uid、email、emailVerified、disabled、metadata、customClaims 等常用字段。查询不到时getUser 返回 nullgetUserByEmail 则抛出 USER_NOT_FOUND 错误。创建用户与匿名登录createUser、createAnonymousUsercreateUser 支持传入 uid、email、password、displayName、phoneNumber 等属性完整字段见 src/auth/auth-request-handler.tscreateAnonymousUser 则直接创建一个匿名账号并返回 idToken 与 refreshToken适合先体验后注册的产品设计。更新与删除用户updateUser、deleteUserupdateUser 可修改邮箱、密码、昵称、头像、手机号、禁用状态等参数类型见 UpdateRequest返回更新后的 UserRecorddeleteUser 则按 uid 彻底删除账号。setCustomUserClaims实现角色权限控制await auth.setCustomUserClaims(uid, { admin: true });设置成功后这些自定义声明会出现在该用户后续的 ID Token 中非常适合实现管理员、VIP 等角色权限体系。常见错误与处理建议USER_NOT_FOUND用户不存在多为 Token 过期或账号已删除可引导用户重新登录USER_DISABLED用户已被禁用需在 Firebase 控制台检查账号状态TOKEN_EXPIRED / NO_MATCHING_KIDToken 过期或密钥轮换可开启 enableTokenRefreshOnExpiredKidHeader 自动刷新INVALID_CREDENTIAL凭证无效通常意味着 refreshToken 已失效需重新登录所有错误类型与错误码定义见 src/auth/error.ts同时还提供了 isUserNotFoundError 等便捷判断函数方便按错误类型分别处理。上手示例与更多资料想快速跑通完整流程推荐直接参考官方示例 examples/next-typescript-starter其中登录 Server Action 的完整写法在 app/actions/login.ts认证配置集中在 config/server-config.ts配置、登录、鉴权、登出一气呵成。git clone https://gitcode.com/gh_mirrors/ne/next-firebase-auth-edge克隆仓库后进入 examples/next-typescript-starter 目录安装依赖即可运行。希望这份 getFirebaseAuth 速查手册能帮你少踩坑、少走弯路早日搞定 Next.js Firebase 认证【免费下载链接】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），仅供参考