Nuxt.js Auth模块API参考：$auth服务的完整使用方法

【免费下载链接】auth-module Zero-boilerplate authentication support for Nuxt 2! 项目地址: https://gitcode.com/gh_mirrors/au/auth-module

Nuxt.js Auth模块（GitHub 加速计划 / au / auth-module）为Nuxt 2提供零样板代码的身份验证支持，通过全局注入的$auth服务，开发者可以轻松实现用户登录、注销、权限控制等功能。本文将详细介绍$auth服务的核心属性、常用方法及最佳实践，帮助新手快速掌握Nuxt.js认证开发。

图：Nuxt Auth模块的零样板认证解决方案

核心属性：实时反映认证状态

$auth服务的属性均为响应式设计，可直接在Vue模板中用于条件渲染。

用户信息（user）

存储已认证用户的详细信息（如姓名、邮箱等），支持两种访问方式：

// 通过$auth实例访问
this.$auth.user

// 通过Vuex状态访问
this.$store.state.auth.user

登录状态（loggedIn）

布尔值标识当前用户是否已认证：

// 检查用户是否登录
if (this.$auth.loggedIn) {
  console.log('用户已登录')
}

常用方法：简化认证流程

登录操作（loginWith）

推荐使用的登录方法，支持指定认证策略（如local、google等）：

// 本地账号登录
this.$auth.loginWith('local', {
  data: {
    email: 'user@example.com',
    password: 'password123'
  }
}).then(() => {
  this.$toast.success('登录成功！')
})

// 第三方OAuth登录（如Google）
this.$auth.loginWith('google', {
  params: {
    scope: 'email profile'
  }
})

用户登出（logout）

清除认证状态并可选重定向：

await this.$auth.logout()
// 登出后自动重定向到配置的logout路径

刷新用户信息（fetchUser）

强制重新获取当前用户信息：

// 用于用户信息更新后同步显示
await this.$auth.fetchUser()

刷新令牌（refreshTokens）

在令牌过期前自动或手动刷新：

// 手动触发令牌刷新
this.$auth.refreshTokens()

令牌管理：安全存储与验证

$auth.strategy提供令牌操作接口，支持获取、设置、验证等功能：

// 获取访问令牌
const token = this.$auth.strategy.token.get()

// 检查令牌状态
const tokenStatus = this.$auth.strategy.token.status()
if (tokenStatus.expired()) {
  console.log('令牌已过期')
}

// 重置令牌
this.$auth.strategy.token.reset()

图：Nuxt Auth模块的令牌管理与认证流程

事件监听：处理认证异常

错误处理（onError）

全局捕获认证过程中的错误：

// 在plugins/auth.js中注册
export default function ({ $auth }) {
  $auth.onError((error, name, endpoint) => {
    console.error(`认证错误[${name}]`, error)
    // 处理令牌过期等异常情况
    if (name === 'token.expired') {
      $auth.logout()
    }
  })
}

重定向控制（onRedirect）

自定义认证相关的重定向行为：

$auth.onRedirect((to, from) => {
  // 动态修改重定向目标
  if (to === '/login') {
    return '/auth/signin'
  }
})

存储操作：跨环境数据持久化

$auth.$storage提供通用存储方案，支持SSR环境下的状态保持：

// 跨存储介质设置数据（Vuex+Cookie+localStorage）
this.$auth.$storage.setUniversal('user_preferences', { theme: 'dark' })

// 获取存储数据
const prefs = this.$auth.$storage.getUniversal('user_preferences')

// 仅操作本地状态
this.$auth.$storage.setState('lastLogin', new Date())

配置选项：自定义认证行为

通过nuxt.config.js中的auth配置项调整全局行为：

// nuxt.config.js
export default {
  auth: {
    redirect: {
      login: '/auth/login',  // 登录页路径
      home: '/dashboard'    // 登录后重定向目标
    },
    token: {
      global: true,         // 自动在所有Axios请求中附加令牌
      prefix: '_auth.'      // 令牌存储键前缀
    }
  }
}

完整配置说明可参考官方文档：docs/content/en/api/options.md

最佳实践总结

1. 策略选择：根据项目需求选择合适的认证策略（本地账号使用local，第三方登录使用oauth2等）
2. 令牌安全：生产环境建议启用cookie.secure: true，确保令牌通过HTTPS传输
3. 错误处理：通过onError统一处理令牌过期、网络异常等场景
4. 状态管理：优先使用$auth实例访问状态，减少直接操作Vuex的耦合

通过$auth服务，Nuxt.js Auth模块大幅简化了认证系统的开发复杂度，让开发者可以专注于业务逻辑实现。无论是简单的本地登录还是复杂的第三方OAuth集成，该模块都能提供一致且易用的API接口。

【免费下载链接】auth-module Zero-boilerplate authentication support for Nuxt 2! 项目地址: https://gitcode.com/gh_mirrors/au/auth-module