v3.16
Nuxt on GitHub

会话与身份验证

身份验证是 Web 应用中极为常见的需求。本教程将向你展示如何在 Nuxt 应用中实现基本的用户注册和身份验证。

介绍

在本教程中，我们将在一个全栈 Nuxt 应用中设置身份验证，使用 Nuxt Auth Utils，它为客户端和服务器端会话数据管理提供了便捷的工具。

该模块使用安全的密封 cookie 来存储会话数据，因此你无需设置数据库来存储会话数据。

安装 nuxt-auth-utils

使用 nuxi CLI 安装 nuxt-auth-utils 模块。

Terminal
npx nuxi@latest module add auth-utils
此命令会将 nuxt-auth-utils 安装为依赖，并将其添加到 nuxt.config.ts 的 modules 部分。

Cookie 加密密钥

由于 nuxt-auth-utils 使用密封 cookie 存储会话数据，会话 cookie 使用来自 NUXT_SESSION_PASSWORD 环境变量的密钥进行加密。

如果未设置此环境变量，在开发模式下运行时，它会自动添加到你的 .env 文件中。
.env
NUXT_SESSION_PASSWORD=a-random-password-with-at-least-32-characters
在部署到生产环境之前，你需要将此环境变量添加到生产环境中。

登录 API 路由

在本教程中，我们将创建一个简单的 API 路由，根据静态数据进行用户登录。

让我们创建一个 /api/login API 路由，接受带有电子邮件和密码的 POST 请求。

server/api/login.post.ts
import { z } from 'zod'

const bodySchema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
})

export default defineEventHandler(async (event) => {
  const { email, password } = await readValidatedBody(event, bodySchema.parse)

  if (email === 'admin@admin.com' && password === 'iamtheadmin') {
    // 在 cookie 中设置用户会话
    // 此服务器工具由 auth-utils 模块自动导入
    await setUserSession(event, {
      user: {
        name: 'John Doe'
      }
    })
    return {}
  }
  throw createError({
    statusCode: 401,
    message: '凭据错误'
  })
})
确保在你的项目中安装 zod 依赖（npm i zod）。
了解更多关于 nuxt-auth-utils 暴露的 setUserSession 服务器辅助函数的信息。

登录页面

该模块暴露了一个 Vue 组合式函数，用于判断用户是否在我们的应用中已通过身份验证：

<script setup>
const { loggedIn, session, user, clear, fetch } = useUserSession()
</script>

让我们创建一个登录页面，包含一个表单，用于将登录数据提交到我们的 /api/login 路由。

pages/login.vue
<script setup lang="ts">
const { loggedIn, user, fetch: refreshSession } = useUserSession()
const credentials = reactive({
  email: '',
  password: '',
})
async function login() {
  $fetch('/api/login', {
    method: 'POST',
    body: credentials
  })
  .then(async () => {
    // 在客户端刷新会话并重定向到首页
    await refreshSession()
    await navigateTo('/')
  })
  .catch(() => alert('凭据错误'))
}
</script>

<template>
  <form @submit.prevent="login">
    <input v-model="credentials.email" type="email" placeholder="电子邮件" />
    <input v-model="credentials.password" type="password" placeholder="密码" />
    <button type="submit">登录</button>
  </form>
</template>

保护 API 路由

保护服务器路由是确保数据安全的关键。客户端中间件对用户体验有帮助，但如果没有服务器端保护，数据仍可能被访问。保护包含敏感数据的路由至关重要，如果用户未登录，我们应返回 401 错误。

auth-utils 模块提供了 requireUserSession 工具函数，帮助确保用户已登录并拥有有效的会话。

让我们创建一个 /api/user/stats 路由示例，仅允许经过身份验证的用户访问。

server/api/user/stats.get.ts
export default defineEventHandler(async (event) => {
  // 确保用户已登录
  // 如果请求未来自有效用户会话，此函数将抛出 401 错误
  const { user } = await requireUserSession(event)

  // TODO：基于用户获取一些统计数据

  return {}
});

保护应用路由

通过服务器端路由保护，我们的数据是安全的，但如果不采取其他措施，未经身份验证的用户在尝试访问 /users 页面时可能会看到一些奇怪的数据。我们应该创建一个 客户端中间件 来保护客户端路由，并将用户重定向到登录页面。

nuxt-auth-utils 提供了一个方便的 useUserSession 组合式函数，我们将使用它来检查用户是否已登录，并在未登录时重定向。

我们将在 /middleware 目录中创建一个中间件。与服务器端不同，客户端中间件不会自动应用于所有端点，我们需要指定应用它的位置。

middleware/authenticated.ts
export default defineNuxtRouteMiddleware(() => {
  const { loggedIn } = useUserSession()

  // 如果用户未通过身份验证，将其重定向到登录页面
  if (!loggedIn.value) {
    return navigateTo('/login')
  }
})

首页

现在我们有了保护路由的应用中间件，我们可以在显示已认证用户信息的主页上使用它。如果用户未通过身份验证，他们将被重定向到登录页面。

我们将使用 definePageMeta 将中间件应用于我们想要保护的路由。

pages/index.vue
<script setup lang="ts">
definePageMeta({
  middleware: ['authenticated'],
})
  
const { user, clear: clearSession } = useUserSession()

async function logout() {
  await clearSession()
  await navigateTo('/login')
}
</script>

<template>
  <div>
    <h1>欢迎 {{ user.name }}</h1>
    <button @click="logout">登出</button>
  </div>
</template>

我们还添加了一个登出按钮，用于清除会话并将用户重定向到登录页面。

结论

我们成功地在 Nuxt 应用中设置了一个非常基本的用户身份验证和会话管理。我们还保护了服务器端和客户端的敏感路由，确保只有经过身份验证的用户可以访问它们。

接下来，你可以：

查看开源的 atidone 仓库，了解一个包含 OAuth 认证、数据库和 CRUD 操作的完整 Nuxt 应用示例。