NextAuth.js 安装与基础配置指南

NextAuth.js 是一个功能强大的身份验证解决方案，专为现代 Web 应用设计。本文将详细介绍如何在不同框架中安装和配置 NextAuth.js，帮助开发者快速构建安全的认证系统。

安装 NextAuth.js

根据您使用的框架，安装对应的 NextAuth.js 包：

Next.js 应用

npm install next-auth@beta

Qwik 应用

使用 Qwik 提供的便捷脚本：

npm run qwik add auth

SvelteKit 应用

npm install @auth/sveltekit

Express 应用

npm install @auth/express

注意：@auth/core 是底层核心库，普通用户无需直接安装和使用。

环境变量配置

NextAuth.js 需要一个关键的 AUTH_SECRET 环境变量，用于加密令牌和邮件验证哈希。您可以通过以下方式生成：

使用 NextAuth.js 提供的工具：

npx auth secret

或者使用 OpenSSL（Linux/Mac 系统自带）：

openssl rand -base64 33

将生成的密钥添加到 .env.local 文件：

AUTH_SECRET=your-generated-secret-here

基础配置

Next.js 配置步骤

1. 创建 auth.ts 配置文件：

import NextAuth from "next-auth"

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [], // 这里将添加认证提供者
})

2. 添加路由处理器（App Router 格式）：

import { handlers } from "@/auth"
export const { GET, POST } = handlers

3. 添加中间件以保持会话活跃：

export { auth as middleware } from "@/auth"

Qwik 配置

使用 Qwik 提供的脚本会自动创建配置文件：

import { QwikAuth$ } from "@auth/qwik"

export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
  () => ({
    providers: [], // 认证提供者配置
  })
)

SvelteKit 配置

1. 创建 auth.ts 文件：

import { SvelteKitAuth } from "@auth/sveltekit"

export const { handle } = SvelteKitAuth({
  providers: [],
})

2. 在 hooks.server.ts 中重新导出：

export { handle } from "./auth"

3. 在布局或页面中访问会话：

export const load: LayoutServerLoad = async (event) => {
  const session = await event.locals.auth()
  return { session }
}

Express 配置

1. 设置认证路由：

import { ExpressAuth } from "@auth/express"
import express from "express"

const app = express()
app.set("trust proxy", true)
app.use("/auth/*", ExpressAuth({ providers: [] }))

后续步骤

完成基础配置后，下一步是添加具体的认证方法（如 Google、GitHub 等 OAuth 提供者或电子邮件认证），填充 providers 数组。

最佳实践建议

1. 生产环境务必使用强密码作为 AUTH_SECRET
2. 根据应用需求选择合适的认证提供者
3. 考虑实现自定义适配器以支持数据库持久化
4. 定期检查会话状态以确保安全性

通过以上步骤，您已经成功搭建了 NextAuth.js 的基础框架，为应用添加了强大的认证能力。后续可以根据具体需求扩展更多功能。