部署 next-firebase-auth-edge 到 Firebase Hosting 与 Cloud Run：完整实战指南

部署 next-firebase-auth-edge 到 Firebase Hosting 与 Cloud Run完整实战指南【免费下载链接】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-firebase-auth-edge 是专为 Next.js 打造的 Firebase Authentication 认证库可同时运行在 Edge 与 Node.js 运行时并兼容最新的 Next.js 特性。本文是一份面向新手的完整实战指南手把手带你完成 next-firebase-auth-edge 部署从 Firebase Hosting 的__sessionCookie 配置到 Google Cloud Run 的免密钥自动认证全程给出可直接复用的配置代码与部署命令。无论你是第一次接触 Next.js 登录功能还是想切换部署平台这份 Firebase Hosting 与 Cloud Run 双方案指南都能帮你少踩坑、快速上线。next-firebase-auth-edge 是什么为什么值得在生产环境使用简单来说next-firebase-auth-edge 帮你把 Firebase 登录状态无缝接入 Next.js 应用。它通过一个中间件authMiddleware自动完成以下工作 自动创建/api/login与/api/logout接口无需手写认证 API 路由 Token 过期时自动刷新浏览器认证 Cookie 使用旋转签名密钥rotating keys对 Cookie 签名降低被破解的风险✅ 在每次请求时校验用户 Cookie 的有效性️ 提供handleValidToken、handleInvalidToken、handleError回调灵活定制登录跳转逻辑官方文档还提供了一个开箱即用的示例工程位于examples/next-typescript-starter/其核心配置集中在proxy.ts与config/server-config.ts两个文件中非常适合作为部署前的参照。部署前的 4 项准备工作无论选择哪个平台你都需要先完成以下基础配置创建 Firebase 项目并在项目中新建一个 Web 应用获取 Web API KeyapiKey启用 Firebase Authentication并开启你需要的登录方式如 Google、邮箱密码等生成服务账号私钥进入「项目设置 → 服务账号 → 生成新的私钥」下载 JSON 凭据其中包含projectId、clientEmail、privateKey配置授权域名在「Authentication → 设置 → 授权域名」中添加你的线上域名如果想先跑通一个完整示例可以克隆示例仓库examples/next-typescript-starter即对应仓库中的同名目录git clone https://gitcode.com/gh_mirrors/ne/next-firebase-auth-edge按examples/next-typescript-starter/README.md的说明填充环境变量即可。方案一部署到 Firebase Hosting完整步骤Firebase Hosting 是最省心的托管方式但有一个关键限制必须提前了解。第一步理解 Firebase Hosting 的 Cookie 限制Firebase Hosting 默认会剥离除__session之外的所有 Cookie。也就是说你的认证 Cookie 名字必须是__session否则登录状态将无法持久化。同时由于该限制Firebase Hosting 环境不支持多 Cookie 模式必须将enableMultipleCookies设为false。第二步配置认证中间件核心代码在项目根目录创建proxy.ts如果你使用 Next.js 14 或 15则创建middleware.ts并导出middleware函数写入以下配置import { NextRequest } from next/server; import { authMiddleware } from next-firebase-auth-edge; export async function proxy(request: NextRequest) { return authMiddleware(request, { cookieName: __session, // Firebase Hosting 必须使用 __session loginPath: /api/login, logoutPath: /api/logout, apiKey: 你的-Firebase-API-Key, cookieSignatureKeys: [至少32字节长度的签名密钥], cookieSerializeOptions: { path: /, httpOnly: true, secure: false, sameSite: lax as const, maxAge: 12 * 60 * 60 * 24, }, serviceAccount: { projectId: 你的项目ID, clientEmail: 你的服务账号邮箱, privateKey: -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n, }, }); } 提示cookieSignatureKeys建议使用两个密钥当前密钥 上一个密钥以实现无感轮换。生产环境请通过环境变量注入不要硬编码。第三步在服务端组件中读取登录状态认证中间件配置好后你可以通过getTokens在 Server Component、Server Action 或 API Route 中读取当前用户信息import { getTokens } from next-firebase-auth-edge; const tokens await getTokens(cookies(), { apiKey: 你的-Firebase-API-Key, cookieName: __session, cookieSignatureKeys: [至少32字节长度的签名密钥], serviceAccount: { /* 同上 */ }, });如果tokens为空说明用户未登录否则可通过tokens.decodedToken获取 uid、邮箱等身份信息。更完整的用法可参考官方文档中的服务端组件指南docs/pages/docs/usage/server-components.mdx。第四步构建并发布到 Firebase Hosting本地确认功能正常后使用 Firebase CLI 一键部署firebase login firebase init hosting # 按提示关联 Firebase 项目 npm run build firebase deploy --only hosting部署完成后你的 Next.js 应用就会运行在 Firebase 提供的 CDN 域名上认证 Cookie 由__session承载登录流程即可正常工作。方案二部署到 Google Cloud Run完整步骤如果你的应用需要更灵活的运行时、自定义域名或更高的并发能力Google Cloud Run 是绝佳选择。而且 next-firebase-auth-edge 在 Cloud Run 上有一个杀手级特性——无需手动配置服务账号私钥。第一步开通 IAM Service Account Credentials API这是免密钥认证的前提。在 Google Cloud 控制台中找到IAM Admin → IAM Service Account Credentials API点击启用。第二步为默认计算服务账号授权 signBlob 权限进入IAM 管理页面找到 Cloud Run 使用的默认计算服务账号为其关联的角色添加iam.serviceAccounts.signBlob权限。授权完成后库就能自动代表该服务账号完成 Token 签名与验证。第三步省略 serviceAccount享受免密钥配置完成上面两步后authMiddleware中的serviceAccount参数可以直接省略——next-firebase-auth-edge 会自动从 Cloud Run 环境中提取凭据。对比 Firebase Hosting你甚至不需要把私钥放进环境变量安全系数更高export async function proxy(request: NextRequest) { return authMiddleware(request, { loginPath: /api/login, logoutPath: /api/logout, apiKey: 你的-Firebase-API-Key, cookieName: AuthToken, // Cloud Run 没有 Cookie 名限制 cookieSignatureKeys: [至少32字节长度的签名密钥], cookieSerializeOptions: { path: /, httpOnly: true, secure: false, sameSite: lax as const, maxAge: 12 * 60 * 60 * 24, }, // 无需 serviceAccount自动从 Cloud Run 环境获取 }); }注意apiKey仍然必须提供。Cookie 名在 Cloud Run 上没有__session限制可以自由命名为AuthToken并且推荐开启enableMultipleCookies: true以承载更大的自定义 Claims。第四步用 Dockerfile 容器化应用Cloud Run 以容器方式运行服务。示例项目examples/next-typescript-starter/Dockerfile提供了一个可直接借鉴的镜像配置FROM node:18.19.0-alpine WORKDIR /usr/app COPY . . RUN yarn install --production RUN yarn build CMD [ yarn, start ]构建镜像后执行以下命令完成 Cloud Run 部署gcloud run deploy next-auth-app \ --image gcr.io/你的项目ID/next-auth-app \ --platform managed \ --region asia-east1 \ --allow-unauthenticated部署完成后访问 Cloud Run 分配的 HTTPS 域名登录、登出、自动刷新全部开箱即用。Firebase Hosting 还是 Cloud Run一张表帮你决策对比维度Firebase HostingGoogle Cloud Run配置难度⭐ 低CLI 一键部署⭐⭐⭐ 需先配置 IAM 与容器Cookie 名必须为__session可自定义如AuthToken多 Cookie 模式❌ 不支持✅ 支持推荐开启服务账号密钥需手动传入serviceAccount免密钥自动从环境获取适用场景纯静态 SSR 轻量应用需要灵活运行时、高并发场景简单建议想最快上线、不想碰 Docker选 Firebase Hosting追求免密钥安全与运行灵活性选 Cloud Run。高频问题与排错锦囊Q1部署到 Firebase Hosting 后登录状态总是丢失检查是否将cookieName设置为__session并把enableMultipleCookies设为false。两者缺一不可详见官方文档docs/pages/docs/usage/firebase-hosting.mdx。Q2Cloud Run 上报 Failed to sign blob 之类的权限错误确认已启用 IAM Service Account Credentials API并且默认计算服务账号拥有iam.serviceAccounts.signBlob权限。Q3使用 Next.js 14/15 应该写middleware.ts还是proxy.tsNext.js 14/15 使用middleware.ts并导出middleware函数Next.js 16 起改名为proxy.ts并导出proxy。两者的authMiddleware参数完全一致参考文档docs/pages/docs/usage/middleware.mdx即可。Q4HTTPS 环境下 Cookie 如何配置将cookieSerializeOptions.secure设为true通过环境变量控制其余保持不变。总结到此你已经掌握了 next-firebase-auth-edge 部署的两条完整路径Firebase Hosting 方案的核心是牢记__sessionCookie 限制与单 Cookie 模式Cloud Run 方案的核心是开通 IAM API 并授权signBlob权限从而享受免密钥认证。建议先从examples/next-typescript-starter/示例跑通本地流程再按本文步骤逐项部署遇到问题时对照文末的排错清单即可快速定位解决。祝你的 Next.js 应用顺利上线【免费下载链接】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），仅供参考