企业官网建设流程全解析

5 分钟快速上手 next-firebase-auth-edge：从零搭建 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

如果你正在为 Next.js 项目寻找一套简单可靠的Firebase 登录方案，那么next-firebase-auth-edge正是你要找的利器。这是一款专为 Next.js Edge Runtime 与 Node.js 运行时设计的 Firebase Authentication 集成库，兼容 App Router、Server Components 等最新特性。本文将用 5 分钟带你从零搭建一套完整的Next.js + Firebase 登录系统，全程无需手写认证 API 路由。

next-firebase-auth-edge 是什么？为何它是 Next.js 登录首选？

官方的firebase-admin严重依赖 Node.js 内置的crypto模块，而该模块在Next.js Edge Runtime中并不可用——这正是很多开发者集成 Firebase 认证时崩溃的根源。

next-firebase-auth-edge通过Web Crypto API完成自定义 ID Token 的签发与校验，完美绕开这一限制：

• ✅ 支持 Next.js 最新特性（App Router、Server Components）
• ✅ 零打包体积（Zero bundle size）
• ✅ 无需自定义 API 路由，一切由中间件（middleware）自动处理
• ✅ 使用 jose 校验 JWT，并用旋转密钥签名 Cookie，安全可靠
• ✅ 支持 Firebase Emulator 本地联调

核心逻辑集中在 src/next/middleware.ts 与 src/auth/auth-request-handler.ts，开箱即用。

第 1 步：安装 next-firebase-auth-edge（一条命令搞定）

使用 npm 或 yarn 均可：

npm install next-firebase-auth-edge

安装完成后，项目的所有登录/登出 Cookie 处理都由库自动接管，你不需要修改next.config.js，也不用创建任何认证接口。

第 2 步：准备环境变量与配置文件

参考官方极简示例 examples/next-typescript-minimal/config.ts，在项目根目录创建config.ts，分为服务端配置与客户端配置：

• serverConfig：Cookie 名称、签名密钥、序列化选项，以及 Firebase 服务账号（projectId、clientEmail、privateKey）
• clientConfig：浏览器端 Firebase 初始化所需的 apiKey、authDomain 等

对应的环境变量包括AUTH_COOKIE_NAME、AUTH_COOKIE_SIGNATURE_KEY_CURRENT、FIREBASE_ADMIN_PRIVATE_KEY、NEXT_PUBLIC_FIREBASE_API_KEY等，在.env.local中填写即可。

第 3 步：用 authMiddleware 一键接入登录态（核心步骤）

这是整套方案中最关键的一步。在项目根目录创建middleware.ts，参考 examples/next-typescript-minimal/middleware.ts：

export async function middleware(request: NextRequest) { return authMiddleware(request, { loginPath: "/api/login", logoutPath: "/api/logout", apiKey: clientConfig.apiKey, cookieName: serverConfig.cookieName, cookieSignatureKeys: serverConfig.cookieSignatureKeys, cookieSerializeOptions: serverConfig.cookieSerializeOptions, serviceAccount: serverConfig.serviceAccount, handleValidToken: async ({token, decodedToken, customToken}, headers) => { // 已登录用户访问 /login、/register 时重定向回首页 return NextResponse.next({ request: { headers } }); }, handleInvalidToken: async (reason) => { return redirectToLogin(request, { path: '/login', publicPaths: PUBLIC_PATHS }); }, handleError: async (error) => { return redirectToLogin(request, { path: '/login', publicPaths: PUBLIC_PATHS }); } }); }

就这样，Token 校验、Cookie 刷新、登录态注入全部自动完成。后续升级到 Server Action 登录时，loginPath与logoutPath依然适用。

第 4 步：创建登录页并获取 ID Token

登录页只需调用 Firebase SDK 的signInWithEmailAndPassword，再携带 ID Token 请求loginPath即可。完整示例见 examples/next-typescript-minimal/app/login/page.tsx：

const credential = await signInWithEmailAndPassword(getAuth(app), email, password); const idToken = await credential.user.getIdToken(); await fetch("/api/login", { headers: { Authorization: `Bearer ${idToken}` } }); router.push("/");

中间件会拦截/api/login请求，校验 ID Token 后自动写入会话 Cookie，登录即告完成。想要支持 Server Action 登录，可参考 login-with-server-action.mdx；登出则调用removeServerCookies方法即可。

第 5 步：在服务端共享用户状态（AuthContext + AuthProvider）

库本身不内置客户端状态管理，建议按官方示例自建：

• 在 auth-context.mdx 中定义AuthContext与useAuthHook，声明User（含 emailVerified、customClaims）类型
• 在 auth-provider.mdx 中实现AuthProvider组件，在服务端组件拿到用户数据后注入 Context

这样 Server Component 与 Client Component 之间即可无缝共享登录状态，页面渲染与权限控制都变得轻松自然。

常见问题与进阶资源

• 页面路由（Pages Router）：同样支持getServerSideProps与传统 API Routes，见 get-server-side-props.mdx
• 刷新凭证：需要令牌自动续期可参考 refresh-credentials.mdx
• App Check 与 Emulator：支持 App Check 校验与 Firebase Emulator 全功能本地联调，见 app-check.mdx 与 emulator.mdx
• 调试模式：排错时可开启 debug 日志，参考 debug-mode.mdx

想快速体验完整效果？直接克隆官方 Starter 示例仓库：

git clone https://gitcode.com/gh_mirrors/ne/next-firebase-auth-edge

其中 examples/next-typescript-starter 包含登录、注册、重置密码、用户资料等完整页面，配置好环境变量后npm run dev即可运行。🚀 从今天开始，让 Next.js + Firebase 登录系统在 5 分钟内落地！

【免费下载链接】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