Next.js认证实战：NextAuth.js + PostgreSQL全栈鉴权架构

1. 项目概述：为什么 Next.js 的认证不是“加个登录页”那么简单

Next.js Authentication 这个标题乍看平平无奇，但如果你真在生产环境里搭过一次用户系统，就会明白它背后藏着的是一整套现代 Web 应用的“信任基建”。它远不止是“前端弹个表单、后端校验密码”——而是要同时扛住 SSR/SSG 的服务端渲染逻辑、客户端水合（hydration）时的状态同步、API 路由与页面路由的权限分流、JWT 或 session 的安全存储与刷新、OAuth 第三方登录的协议适配、以及数据库层（比如 PostgreSQL）中用户凭证、角色、会话、令牌的原子化管理。我去年给一个 SaaS 后台做重构时，就因为低估了 Next.js 认证的上下文隔离性，在getServerSideProps里读不到req.session，硬是卡了三天才搞清 NextAuth.js 的 adapter 机制和 session 策略差异。

关键词里反复出现的NextAuth.js不是可选项，而是事实标准；而PostgreSQL的高频出现，恰恰说明真实项目早已越过 SQLite 或内存 session 的玩具阶段——你需要的是能支撑 RBAC（基于角色的访问控制）、审计日志、多租户隔离、以及与 pgvector 等扩展协同工作的持久化底座。那些热搜词里混杂的dbeaver的postgres表在哪里、postgresql和mysql区别、甚至insufficient privilege: 7 error: must be able to set role 'postgres，都不是偶然。它们暴露了一个现实：90% 的 Next.js 认证失败，根源不在 Next.js 或 NextAuth.js，而在开发者对 PostgreSQL 权限模型、连接池行为、SSL 配置、甚至.pgpass文件加载时机的陌生。这不是语法问题，是基础设施认知断层。

所以这篇内容，不讲“如何安装 NextAuth.js”，而是带你从零推演：当一个 Next.js 应用需要支持邮箱密码登录 + GitHub OAuth + 2FA 备用验证，并把所有状态存进 PostgreSQL 时，你必须亲手决策的 7 个关键节点——每个节点都附带我在三个不同客户项目中踩过的坑、实测有效的参数组合、以及 PostgreSQL 命令行里一句就能查清问题的诊断命令。适合两类人：一是刚用npx create-next-app@latest初始化完项目、正对着app/(auth)/login/page.tsx发呆的中级开发者；二是已经上线但发现“登录后跳转丢失”“SSR 页面报 401”“PostgreSQL 连接池爆满”的运维/全栈工程师。接下来的内容，每一句都能直接抄进你的next.config.js或prisma/schema.prisma里跑通。

2. 整体架构设计：为什么必须放弃“前端鉴权幻觉”

2.1 Next.js 认证的三重上下文陷阱

Next.js 的核心矛盾在于：它既是前端框架，又是服务端运行时。这就导致认证逻辑天然分裂成三个互不信任的“王国”：

• 客户端（Browser）：React 组件、useSession()Hook、浏览器 Cookie 存储。这里的问题是“不可信”——用户可以禁用 JS、篡改 localStorage、伪造session对象。我见过最离谱的案例，是某电商后台用localStorage.setItem('userRole', 'admin')控制菜单显示，结果被爬虫直接绕过登录页，靠暴力猜 URL 抓取了全部订单 API。

• 服务端（Node.js Runtime）：getServerSideProps、generateStaticParams、Route Handlers（App Router 的/api/*）。这里是真正的“守门人”，但 Next.js 默认不共享客户端 Cookie 到服务端请求头——除非你显式配置credentials: 'include'并处理 CORS。更致命的是，Next.js 13+ App Router 的fetch()默认不发送 Cookie，你得手动加cache: 'no-store'和credentials: 'include'，否则GET /api/user/profile永远拿不到 session。

• 数据库（PostgreSQL）：用户表、会话表、账户表、验证器表（2FA）、授权码表（OAuth）。这里的问题是“过度设计”——很多团队一上来就建users,sessions,accounts,verification_tokens四张表，结果发现accounts表根本没用（GitHub 登录只用provider和providerAccountId），而verification_tokens表因 TTL 设置不当，半年积压 200 万条失效记录，导致SELECT * FROM verification_tokens WHERE identifier = $1 AND expires > NOW()查询耗时从 2ms 涨到 1.8s。

提示：NextAuth.js 的adapter不是“插件”，而是数据契约。你选PrismaAdapter还是TypeORMAdapter，决定的不是“怎么连数据库”，而是“哪些字段必须存在、哪些索引必须建立、哪些外键关系必须强制”。PostgreSQL 的ON DELETE CASCADE在accounts表上若没配好，用户删 GitHub 账号时，users表主键被级联删除，整个账号体系就崩了。

2.2 NextAuth.js 的策略选型：Session vs JWT，没有中间路线

NextAuth.js 提供两种 session 存储模式，选错一种，后续所有优化都是徒劳：

• Database Session（推荐用于生产）：session 数据存 PostgreSQL 的sessions表，token字段是随机字符串（非 JWT），expires字段控制过期。优势是：可主动销毁（await auth().update({ session: { expires: new Date(0) } })）、支持多实例部署、天然防 token 重放。劣势是：每次请求都要查一次 DB，必须配连接池。我在线上用 PgBouncer + 50 连接池，平均查询延迟 3.2ms，完全可接受。

• JWT Session（仅限开发/简单场景）：session 数据编码进 JWT，存在 Cookie 里。优势是：零 DB 查询、适合无状态部署。劣势是：无法主动登出（只能等过期）、JWT 一旦泄露即永久有效、2FA 二次验证无法嵌入（JWT 签发后无法动态追加twoFactorVerified: true字段）。我们曾用 JWT 模式上线一个内部工具，结果某员工电脑中毒，JWT 被窃取，攻击者用它调用了 37 次/api/admin/delete-all，直到过期。

注意：JWT 模式下secret必须是 32 字节以上随机字符串（openssl rand -base64 32），绝不能用"my-secret"这种明文。而 Database 模式下secret仅用于加密 Cookie，长度要求宽松，但必须和NEXTAUTH_SECRET环境变量一致，否则客户端 Cookie 无法解密。

2.3 PostgreSQL 作为认证底座的不可替代性

为什么不用 MySQL？不是性能，是语义。PostgreSQL 的JSONB类型让user.metadata字段可直接存任意结构（如{ "twoFactor": { "enabled": true, "method": "totp" } }），查询时用WHERE metadata @> '{"twoFactor": {"enabled": true}}'一行搞定；MySQL 的 JSON 类型不支持 GIN 索引，复杂查询必全表扫描。更关键的是ROW LEVEL SECURITY (RLS)—— 当你要实现“用户只能查自己的订单”，在 PostgreSQL 里只需：

CREATE POLICY user_orders_policy ON orders FOR SELECT USING (user_id = current_setting('app.current_user_id', true)::UUID);

然后在 NextAuth.js 的callbacks.session()里注入app.current_user_id。MySQL 做不到这种细粒度、可开关的行级权限。

那些热搜词里反复出现的insufficient privilege: 7 error: must be able to set role 'postgres，本质就是 RLS 策略里current_setting()读不到值。解决方案不是给应用用户postgres角色，而是用SET LOCAL app.current_user_id = 'xxx'在事务内设置，或在 PgBouncer 的auth_file里预设。

3. 核心细节解析：从 NextAuth.js 配置到 PostgreSQL 表结构

3.1 NextAuth.js 的最小可行配置（App Router）

别被官方文档的 200 行配置吓到。一个能跑通邮箱密码 + GitHub 登录 + 2FA 的auth.ts，核心就这 12 行：

// app/api/auth/[...nextauth]/route.ts import NextAuth from "next-auth"; import Credentials from "next-auth/providers/credentials"; import Github from "next-auth/providers/github"; import { PrismaAdapter } from "@auth/prisma-adapter"; import { PrismaClient } from "@prisma/client"; import { compare } from "bcrypt"; const prisma = new PrismaClient(); export const { handlers, auth, signIn, signOut } = NextAuth({ adapter: PrismaAdapter(prisma), providers: [ Credentials({ name: "Credentials", credentials: { email: { label: "Email", type: "email" }, password: { label: "Password", type: "password" } }, async authorize(credentials) { if (!credentials?.email || !credentials?.password) return null; const user = await prisma.user.findUnique({ where: { email: credentials.email.toLowerCase() } }); if (!user || !(await compare(credentials.password, user.password))) return null; // 2FA 检查：若启用且未验证，返回特殊对象触发 2FA 流程 if (user.twoFactorEnabled && !user.twoFactorVerified) { return { id: user.id, twoFactorRequired: true }; } return user; } }), Github({ clientId: process.env.GITHUB_ID!, clientSecret: process.env.GITHUB_SECRET! }) ], callbacks: { async session({ session, user }) { if (session.user) { session.user.id = user.id; session.user.twoFactorEnabled = user.twoFactorEnabled; } return session; } } });

关键点解析：

• PrismaAdapter(prisma)：自动映射users,accounts,sessions,verification_tokens四张表。你不用手写 SQL，但必须确保prisma.schema里有对应模型。
• authorize()返回null表示失败，返回{ id: 'xxx', twoFactorRequired: true }表示需二次验证——NextAuth.js 会自动跳转到/api/auth/callback/credentials?callbackUrl=/2fa。
• callbacks.session()是唯一能向客户端 session 注入自定义字段的地方。twoFactorEnabled必须在这里加，否则useSession()拿不到。

3.2 PostgreSQL 表结构：精简到只剩 3 张表

Prisma Adapter 默认建 4 张表，但verification_tokens可以合并进users表（用two_factor_token和two_factor_expires字段），accounts表若只用邮箱登录可删。最终线上稳定版只有 3 张表：

-- users 表：核心用户信息 CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT, email TEXT UNIQUE NOT NULL, email_verified TIMESTAMP WITH TIME ZONE, password TEXT, -- 仅邮箱登录时有值，GitHub 登录为空 two_factor_enabled BOOLEAN DEFAULT false, two_factor_secret TEXT, -- TOTP 密钥（base32） two_factor_token TEXT, -- 临时验证码（6 位数字） two_factor_expires TIMESTAMP WITH TIME ZONE, created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() ); -- sessions 表：会话状态（Database Session 模式必需） CREATE TABLE sessions ( id TEXT PRIMARY KEY, session_token TEXT UNIQUE NOT NULL, user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, expires TIMESTAMP WITH TIME ZONE NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() ); CREATE INDEX idx_sessions_user_id ON sessions(user_id); CREATE INDEX idx_sessions_expires ON sessions(expires); -- 为 2FA 令牌加复合索引，避免全表扫描 CREATE INDEX idx_users_2fa_token ON users(two_factor_token) WHERE two_factor_token IS NOT NULL;

实操心得：users.email必须建UNIQUE约束，否则两个用户注册同邮箱，PrismaAdapter会静默失败。而sessions.expires索引是救命的——没有它，每分钟 1000 次登录请求，DELETE FROM sessions WHERE expires < NOW()会锁表 3 秒以上。

3.3 PostgreSQL 连接池与 SSL：绕不开的生产配置

Next.js 应用启动时，Prisma Client 会创建连接池。默认max是 10，但线上 100 QPS 就会排队。必须在prisma/schema.prisma里显式配置：

generator client { provider = "prisma-client-js" previewFeatures = ["postgresqlExtensions"] } datasource db { provider = "postgresql" url = env("DATABASE_URL") // 关键：连接池参数 directUrl = env("DIRECT_DATABASE_URL") // 用于迁移，不走连接池 relationMode = "prisma" } // 连接池参数必须写在 DATABASE_URL 里，不能单独配 // 正确格式：postgresql://user:pass@host:5432/db?connection_limit=50&sslmode=require

DATABASE_URL的完整写法（含 SSL）：

postgresql://myuser:mypass@mydb.postgres.database.azure.com:5432/mydb?schema=public&connection_limit=50&sslmode=require&sslcert=/path/to/server.crt&sslkey=/path/to/server.key&sslrootcert=/path/to/ca.crt

• connection_limit=50：Prisma 连接池最大连接数，建议设为应用实例数 × 10（如 5 个 PM2 实例，设 50）。
• sslmode=require：强制 SSL，否则 Azure/AWS RDS 会拒绝连接。
• sslcert/sslkey/sslrootcert：公私钥路径，本地开发可省略，但 CI/CD 必须提供。

常见问题：error: certificate verify failed。这不是证书问题，是 Node.js 版本太低（<18.17）。升级 Node.js，或在next.config.js里加：

module.exports = { webpack: (config) => { config.resolve.fallback = { ...config.resolve.fallback, fs: false, path: false, os: false, crypto: false }; return config; } };

3.4 2FA 实现：TOTP 的 5 个硬核步骤

热搜词里高频出现的enter the code from your two-factor authentication app，背后是 RFC 6238 标准的 TOTP（基于时间的一次性密码）。NextAuth.js 不内置，需自己实现：

1. 生成密钥：用户开启 2FA 时，用speakeasy.generateSecret({ length: 20 })生成 base32 密钥，存users.two_factor_secret。
2. 生成二维码：用qrcode.toDataURL()生成otpauth://totp/MyApp:user@email.com?secret=XXXX&issuer=MyApp，前端扫码。
3. 验证首码：用户输入 App 里显示的 6 位数字，用speakeasy.totp.verify({ secret: user.two_factor_secret, encoding: 'base32', token: input })校验。
4. 标记启用：校验成功后，UPDATE users SET two_factor_enabled = true WHERE id = $1。
5. 登录时拦截：在authorize()里检查if (user.twoFactorEnabled && !user.twoFactorVerified)，返回{ twoFactorRequired: true }，NextAuth.js 自动跳转。

注意：speakeasy.totp.verify()的window参数默认是 0（精确匹配），生产环境必须设window: 2（允许前后 2 分钟偏差），否则用户手机时间慢 90 秒就永远登不上。

4. 实操过程：从初始化到生产部署的 8 个关键环节

4.1 初始化项目与依赖安装

别用npm create next-app@latest默认模板——它不带 TypeScript 和 Auth 支持。按这个顺序执行：

# 1. 创建项目（强制 TypeScript） npx create-next-app@latest my-auth-app --typescript --tailwind --eslint # 2. 进入目录，安装核心依赖 cd my-auth-app npm install next-auth @auth/prisma-adapter prisma @prisma/client bcrypt speakeasy qrcode # 3. 初始化 Prisma（PostgreSQL 专用） npx prisma init # 修改 prisma/schema.prisma 的 datasource 为 postgresql # 运行迁移（首次） npx prisma migrate dev --name init

prisma/schema.prisma的最小化配置：

model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? password String? twoFactorEnabled Boolean @default(false) twoFactorSecret String? twoFactorToken String? twoFactorExpires DateTime? accounts Account[] sessions Session[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Account { id String @id @default(cuid()) userId String type String provider String providerAccountId String refresh_token String? access_token String? expires_at Int? token_type String? scope String? id_token String? session_state String? user User @relation(fields: [userId], references: [id], onDelete: Cascade) @@unique([provider, providerAccountId]) } model Session { id String @id @default(cuid()) sessionToken String @unique userId String expires DateTime user User @relation(fields: [userId], references: [id], onDelete: Cascade) }

提示：cuid()比uuid()更安全——UUIDv4 可被预测，而 cuid 用时间戳+随机数+计数器，无法被暴力枚举。@@unique([provider, providerAccountId])是关键，它保证同一个 GitHub 用户不会重复创建accounts记录。

4.2 开发环境 PostgreSQL 配置（Docker 一键启动）

本地开发别折腾源码编译。用 Docker 启一个带 pgvector 的 PostgreSQL：

# docker-compose.yml version: '3.8' services: db: image: ankane/pgvector:latest environment: POSTGRES_DB: myauth POSTGRES_USER: myuser POSTGRES_PASSWORD: mypass ports: - "5432:5432" volumes: - ./pgdata:/var/lib/postgresql/data command: > postgres -c 'max_connections=100' -c 'shared_buffers=256MB' -c 'effective_cache_size=1GB' -c 'work_mem=4MB' -c 'maintenance_work_mem=64MB'

启动后，进容器执行：

docker exec -it my-auth-app-db-1 psql -U myuser -d myauth # 创建扩展（为未来 pgvector 做准备） CREATE EXTENSION IF NOT EXISTS vector; # 创建用户角色（解决热搜里的 insufficient privilege） CREATE ROLE nextjs_app LOGIN PASSWORD 'app123'; GRANT CONNECT ON DATABASE myauth TO nextjs_app; GRANT USAGE ON SCHEMA public TO nextjs_app; GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO nextjs_app; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO nextjs_app;

实测心得：max_connections=100是底线。Next.js 开发服务器热重载时，Prisma 会频繁新建连接，不设高限，FATAL: remaining connection slots are reserved for non-replication superuser connections错误每 5 分钟报一次。

4.3 环境变量安全配置（.env.local）

.env.local必须包含这些（严禁提交到 Git）：

# NextAuth.js NEXTAUTH_SECRET=2b3a1c5e8f0d9a7c6b4e2f1a0d9c8b7a6e5f4d3c2b1a0f9e8d7c6b5a4f3e2d1c NEXTAUTH_URL=http://localhost:3000 # PostgreSQL DATABASE_URL="postgresql://myuser:mypass@localhost:5432/myauth?schema=public&connection_limit=50" # GitHub OAuth（去 GitHub Settings > Developer settings > OAuth Apps 创建） GITHUB_ID=your_github_client_id GITHUB_SECRET=your_github_client_secret # SMTP（邮箱验证用，用 Mailgun 或 Resend） SMTP_HOST=smtp.mailgun.org SMTP_PORT=587 SMTP_USER=postmaster@yourdomain.com SMTP_PASS=your_mailgun_password

注意：NEXTAUTH_SECRET必须是 32 字节以上随机字符串。用openssl rand -base64 32生成，别手打。DATABASE_URL里的connection_limit=50必须和 Prisma 配置一致，否则连接池争抢。

4.4 登录流程实操：从页面到数据库的完整链路

以邮箱密码登录为例，走一遍真实请求：

1. 前端：app/(auth)/login/page.tsx提交表单到/api/auth/callback/credentials
2. NextAuth.js：触发providers.Credentials.authorize()，执行：

   const user = await prisma.user.findUnique({ where: { email: credentials.email.toLowerCase() } }); // 若 user.twoFactorEnabled=true 且 user.twoFactorVerified=false // 则返回 { id: user.id, twoFactorRequired: true } // NextAuth.js 自动重定向到 /2fa 页面

3. 2FA 页面：app/2fa/page.tsx显示输入框，提交到/api/auth/two-factor
4. 自定义 Route Handler（app/api/auth/two-factor/route.ts）：

   export async function POST(req: Request) { const { token } = await req.json(); const session = await getServerSession(authOptions); if (!session?.user?.id) return Response.json({ error: 'Unauthorized' }, { status: 401 }); const user = await prisma.user.findUnique({ where: { id: session.user.id } }); const verified = speakeasy.totp.verify({ secret: user.twoFactorSecret!, encoding: 'base32', token, window: 2 // 允许 ±2 分钟 }); if (verified) { await prisma.user.update({ where: { id: user.id }, data: { twoFactorVerified: true } }); return Response.json({ success: true }); } return Response.json({ error: 'Invalid token' }, { status: 400 }); }

5. 数据库：UPDATE users SET twoFactorVerified = true WHERE id = 'xxx'

关键调试技巧：在authorize()里加console.log('User found:', user)，但别在生产环境留着——Next.js 日志会暴露密码哈希。用prisma.$queryRaw执行SELECT * FROM users WHERE email = ${email}查原始数据，比 ORM 更快定位问题。

4.5 生产部署：Vercel + Railway 的零配置组合

Vercel 部署 Next.js，Railway 部署 PostgreSQL，两者通过环境变量打通：

• Vercel 项目设置：

  • Environment Variables添加DATABASE_URL（值为 Railway 的 PostgreSQL 连接串）
  • NEXTAUTH_SECRET（用 Vercel CLI 生成：vercel secrets add nextauth-secret $(openssl rand -base64 32)）
  • NEXTAUTH_URL设为https://your-app.vercel.app

• Railway 项目设置：

  • 新建 PostgreSQL 服务，选择1 GB RAM规格
  • 在Variables里添加PGPASSWORD（数据库密码）
  • 连接串格式：postgresql://railway:railway@containers-us-west-18.railway.app:7062/railway?connection_limit=50

实测数据：Vercel Serverless Functions 的冷启动约 800ms，但getServerSession()在 warm instance 上平均 12ms。Railway 的 PostgreSQL 连接延迟稳定在 25ms 内，比自建 AWS RDS 便宜 60%。

4.6 权限控制：保护 API 路由与静态页面

不是所有页面都需要登录。用getServerSession()做 SSR 保护：

// app/dashboard/page.tsx import { getServerSession } from "@/auth"; import { redirect } from "next/navigation"; export default async function Dashboard() { const session = await getServerSession(); if (!session) { redirect("/login"); } return <div>Welcome, {session.user?.name}!</div>; }

保护 API 路由（app/api/data/route.ts）：

import { getServerSession } from "@/auth"; export async function GET(req: Request) { const session = await getServerSession(); if (!session || !session.user) { return Response.json({ error: 'Unauthorized' }, { status: 401 }); } // 查询用户专属数据 const data = await prisma.order.findMany({ where: { userId: session.user.id } }); return Response.json(data); }

注意：getServerSession()在generateStaticParams()里不能用（SSG 无 session），必须用auth()的getSession()替代，且要处理null。

4.7 日志与监控：快速定位认证失败

在pages/_app.tsx或app/layout.tsx里加全局错误捕获：

'use client'; import { useEffect } from 'react'; import { useSession } from 'next-auth/react'; export default function MyApp({ Component, pageProps }: any) { const { status } = useSession(); useEffect(() => { if (status === 'unauthenticated') { console.warn('[Auth] Session expired or invalid. Redirecting to login.'); window.location.href = '/login'; } }, [status]); return <Component {...pageProps} />; }

PostgreSQL 侧，建视图查异常登录：

CREATE VIEW failed_login_attempts AS SELECT ip_address, COUNT(*) as attempts, MAX(created_at) as last_attempt FROM auth_logs WHERE success = false AND created_at > NOW() - INTERVAL '1 hour' GROUP BY ip_address HAVING COUNT(*) > 5;

实操心得：auth_logs表需手动建，记录ip_address,user_id,success,created_at。用pg_stat_statements扩展查慢查询：SELECT query, total_time FROM pg_stat_statements ORDER BY total_time DESC LIMIT 5，能快速发现SELECT * FROM sessions WHERE session_token = $1没走索引的问题。

4.8 安全加固：修复热搜词里的高危漏洞

热搜词pop3 server allows plain text authentication vulnerability提醒我们：任何认证系统都可能暴露明文凭据。加固点：

• 密码哈希：bcrypt.hash(password, 12)，12是 cost factor，太高拖慢登录，太低易被爆破。实测12在 2023 年平衡点。
• Cookie 安全：NextAuth.js 默认httpOnly: true, secure: true, sameSite: 'lax'，但必须确保NEXTAUTH_URL是 HTTPS，否则secure: true会让 Cookie 不发送。
• CSRF 保护：NextAuth.js 自动处理，但自定义POST /api/auth/two-factor必须加 CSRF Token：

  // 在登录成功后，生成 token 存 session await prisma.session.update({ where: { sessionToken: sessionToken }, data: { csrfToken: crypto.randomUUID() } });

• 速率限制：用@upstash/ratelimit限制/api/auth/callback/credentials每 IP 每分钟 5 次：

  import { Ratelimit } from '@upstash/ratelimit'; import { Redis } from '@upstash/redis'; const ratelimit = new Ratelimit({ redis: Redis.fromEnv(), limiter: Ratelimit.slidingWindow(5, '1 m'), }); export async function POST(req: Request) { const ip = req.headers.get('x-forwarded-for') || 'unknown'; const { success } = await ratelimit.limit(ip); if (!success) return Response.json({ error: 'Too many requests' }, { status: 429 }); // ... }

5. 常见问题与排查技巧实录：来自 37 个生产项目的血泪总结

5.1 “登录后跳转丢失”问题排查表

独家技巧：在app/api/auth/[...nextauth]/route.ts顶部加console.log('Auth route hit with headers:', JSON.stringify(req.headers))，看cookie头是否包含next-auth.session-token=xxx。没有，说明前端没发 Cookie；有但服务端解不出，说明NEXTAUTH_SECRET错。

5.2 PostgreSQL 连接相关错误速查

实测经验：pg_hba.conf的host规则必须放在local规则之后，否则local的peer认证会优先匹配，导致psql -U myuser成功但应用连接失败。

5.3 NextAuth.js 特定问题避坑指南

5.4 2FA 相关故障处理清单