部署 next-firebase-auth-edge 到 Firebase Hosting 与 Cloud Run：完整实战指南
项目地址: https://gitcode.com/gh_mirrors/ne/next-firebase-auth-edge next-firebase-auth-edge 是专为 Next.js 打造的 Firebase Authentication 认证库，可同时运行在 Edge 与 Node.js 运行时，并兼容最新的 Next.js 特性。本文是一份面向新手的完整实战指南，手把手带你完成 next-firebase-auth-edge 部署：从 Firebase Hosting 的 __session Cookie 配置，到 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 Key（
apiKey） - 启用 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 Hosting | Google 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。
Q2：Cloud Run 上报 "Failed to sign blob" 之类的权限错误？ 确认已启用 IAM Service Account Credentials API，并且默认计算服务账号拥有 iam.serviceAccounts.signBlob 权限。
Q3：使用 Next.js 14/15 应该写 middleware.ts 还是 proxy.ts？ Next.js 14/15 使用 middleware.ts 并导出 middleware 函数；Next.js 16 起改名为 proxy.ts 并导出 proxy。两者的 authMiddleware 参数完全一致，参考文档 docs/pages/docs/usage/middleware.mdx 即可。
Q4：HTTPS 环境下 Cookie 如何配置？ 将 cookieSerializeOptions.secure 设为 true（通过环境变量控制），其余保持不变。
总结
到此，你已经掌握了 next-firebase-auth-edge 部署的两条完整路径：Firebase Hosting 方案的核心是牢记 __session Cookie 限制与单 Cookie 模式；Cloud Run 方案的核心是开通 IAM API 并授权 signBlob 权限，从而享受免密钥认证。建议先从 examples/next-typescript-starter/ 示例跑通本地流程，再按本文步骤逐项部署，遇到问题时对照文末的排错清单，即可快速定位解决。祝你的 Next.js 应用顺利上线！🚀
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
