nuxt-users

Nuxt Users 技能

初始设置

1. 安装模块和同级依赖

   npm install nuxt-users
   npm install db0 better-sqlite3 bcrypt nodemailer
   

   对于 MySQL 或 PostgreSQL，请根据需要安装对应的驱动（mysql2 或 pg），替代 better-sqlite3，或在其基础上额外安装。

2. 在 nuxt.config.ts 中注册模块

   export default defineNuxtConfig({
     modules: ['nuxt-users']
   })
   

3. 运行迁移 在项目根目录（nuxt.config.ts 所在目录）中运行：

   npx nuxt-users migrate
   

4. 至少创建一个用户

   npx nuxt-users create-user -e [email protected] -n "Admin User" -p password123 -r admin
   

   参数：-e 表示电子邮箱，-n 表示姓名，-p 表示密码，-r 表示角色（可选）。

5. 配置权限

   export default defineNuxtConfig({
     modules: ['nuxt-users'],
     nuxtUsers: {
       auth: {
         permissions: {
           admin: ['*'],
           user: ['/profile', '/api/nuxt-users/me']
         }
       }
     }
   })
   

6. 在页面中使用登录功能

   • 使用 NUsersLoginForm 组件，并在 @success 事件中调用 useAuthentication() 返回的 login(user)。
   • 可选：登录后重定向（例如 navigateTo('/')）。

配置参考（nuxt.config.ts）

所有选项都位于 nuxt.config.ts 中的 nuxtUsers 下。

区域	键	说明
数据库	connector.name	'sqlite' | 'mysql' | 'postgresql'
数据库	connector.options	path（SQLite），或 host、port、user、password、database（MySQL/PostgreSQL）
API	apiBasePath	默认值为 '/api/nuxt-users'
表	tables.users、tables.personalAccessTokens、tables.passwordResetTokens、tables.migrations	自定义表名
邮件程序	mailer	用于发送密码重置邮件的 Nodemailer 配置
URL	passwordResetUrl、emailConfirmationUrl	重定向路径
认证	auth.whitelist	公共路由（例如 ['/register']）；/login 始终为公共路由
认证	auth.tokenExpiration	分钟数（默认值为 1440）
认证	auth.rememberMeExpiration	天数（默认值为 30）
认证	auth.permissions	角色 → 路径（例如 admin: ['*']、user: ['/profile']）。键为预定义角色。
认证	auth.allowCustomRoles	默认值为 false。设为 true 时，创建/更新 API 和 NUsersUserForm 接受未列在 permissions 中的角色。空的 permissions（引导配置）本身就接受任意角色。
认证	auth.google	Google OAuth：clientId、clientSecret、callbackUrl 等。
密码	passwordValidation	minLength、requireUppercase、requireLowercase、requireNumbers、requireSpecialChars、preventCommonPasswords
数据	hardDelete	true = 硬删除，false = 软删除（默认值）
区域设置	locale.default、locale.texts、locale.fallbackLocale	本地化
同时也支持运行时配置：使用 runtimeConfig.nuxtUsers 设置基于环境变量或仅限服务端的选项。

CLI 命令

请从项目根目录运行，以便找到 nuxt.config.ts（以及可选的 .env）。

• 迁移

  npx nuxt-users migrate
  

• 创建用户

  npx nuxt-users create-user -e <email> -n "<name>" -p <password> [-r <role>]
  

  除非 auth.allowCustomRoles 为 true（或权限列表为空），否则角色必须与某个 auth.permissions 键匹配。

• 旧版／表创建

  npx nuxt-users create-users-table
  npx nuxt-users create-personal-access-tokens-table
  npx nuxt-users create-password-reset-tokens-table
  npx nuxt-users create-migrations-table
  

生产环境： CLI 要求在 Node 运行的位置安装 nuxt-users（及其同级依赖），它不会打包在 .output/ 中。完整配置需要应用根目录中包含 nuxt.config；仅构建或使用 --omit=dev 部署时，则会回退到 DB_* 环境变量。请参阅 docs/user-guide/configuration.md。

组合式函数（自动导入）

• useAuthentication() — user、isAuthenticated、login(user, rememberMe?)、logout()、fetchUser(useSSR?)、initializeUser()
• useUsers() — 管理员：users、pagination、loading、error、fetchUsers(page?, limit?)、updateUser、addUser、removeUser(userId)
• usePublicPaths() — getPublicPaths()、getAccessiblePaths()、isPublicPath(path)、isAccessiblePath(path, method?)
• usePasswordValidation(moduleOptions?, options?) — validate(password)、isValid、errors、strength、score、clearValidation()
• useNuxtUsersLocale() — t(key, params?)、currentLocale、fallbackLocale

组件

• NUsersLoginForm — 登录表单；使用 @success 调用 useAuthentication() 中的 login(user)
• NUsersLogoutLink — 注销链接／按钮
• NUsersProfileInfo — 显示个人资料
• NUsersResetPasswordForm — 重置密码表单
• NUsersList — 用户列表（管理员）
• NUsersUserForm — 创建／编辑用户表单；角色下拉选项来自 auth.permissions 键；设置 auth.allowCustomRoles: true 可提供自定义自由文本角色选项

故障排查

症状	解决方法
访问受保护路由时被重定向到登录页	设置 auth.permissions，确保每个角色都能访问所需路由
找不到 CLI 配置／表名错误	从包含 nuxt.config 的目录运行 CLI；请参阅上方的生产环境说明
缺少迁移表	在项目根目录运行 npx nuxt-users migrate
数据库驱动错误	安装正确的同级依赖：SQLite → better-sqlite3，MySQL → mysql2，PostgreSQL → pg

文件参考

• 项目 LLM 上下文和配置类型：仓库根目录中的 llms.txt
• 完整文档：https://nuxt-users.webmania.cc/
• 入门指南和示例：../../docs/user-guide/getting-started.md、../../docs/examples/basic-setup.md
• 授权：../../docs/user-guide/authorization.md
• 配置详情：../../docs/user-guide/configuration.md

请确保 nuxtUsers 配置和权限与应用的角色和路由保持同步；实现自定义身份验证逻辑时，请使用守卫子句和提前返回。