useLoginCheck()

useLoginCheck() 是 framework 鉴权体系的核心 composable。在业务操作前调用，未登录时按 mode 自动引导用户（页面跳转或弹窗），已登录直接放行。

签名：useLoginCheck(options?): Promise<boolean> —— 直接返回 Promise（已登录 true / 未登录 false）；不是返回包含 isLoggedIn 的对象。

基础用法

<script setup lang="ts">
async function submitComment() {
  // 未登录时跳转 /login?redirect=当前路径，已登录返回 true
  if (!(await useLoginCheck())) return

  await request('/comment/add', { body: { content: text.value } })
}
</script>

弹窗模式（桌面端推荐）

桌面端点赞、收藏等不希望"跳走"的轻交互，用弹窗登录：

<script setup lang="ts">
const { open } = useLoginDialog()

async function onLike() {
  if (!(await useLoginCheck({ mode: 'dialog', openDialog: open }))) return

  await request('/like/toggle', { body: { id } })
}
</script>

强制登录后不返回原页

敏感操作（如修改邮箱后跳首页确认信息）用 redirectBack: false：

await useLoginCheck({ redirectBack: false })

参数

参数	类型	默认	说明
`mode`	`'page' \| 'dialog'`	`'page'`	未登录时的引导方式：`page` 跳转 `/login`；`dialog` 调 `openDialog` 弹窗
`redirectBack`	`boolean`	`true`	登录后是否带 `?redirect=当前路径` 返回（`mode: 'page'` 时有效）
`openDialog`	`() => void`	—	`mode: 'dialog'` 时调用此函数打开弹窗。通常传 `useLoginDialog()` 的 `open`

返回值

Promise<boolean> —— true = 已登录，可继续业务；false = 未登录，已自动引导（页面已跳转或弹窗已打开），调用方应 early return

直接返回 Promise<boolean>，不是对象。当前签名见源码 src/runtime/composables/useLoginCheck.ts。

与全局响应式登录状态的关系

判断"用户当前是否已登录"用 useUserStore() 的 isLoggedIn（响应式 ref，跨标签页 cookie 同步）：

<template>
  <div v-if="userStore.isLoggedIn">
    <UserProfile />
  </div>
  <div v-else>
    <NuxtLink to="/login">请登录后查看</NuxtLink>
  </div>
</template>

<script setup lang="ts">
const userStore = useUserStore()
</script>

useLoginCheck() 是一次性副作用（"未登录就引导"），不要在模板里 await 它当响应式状态用。

与路由守卫的关系

framework 内置的 login.global middleware 不调用 useLoginCheck()，而是直接读 userStore.isLoggedIn 判断（更轻量，无副作用）。守卫路径在 nuxt.config.ts 的 swiftConfig.auth.guardedPaths 配置：

// nuxt.config.ts
export default defineNuxtConfig({
  swiftConfig: {
    auth: {
      guardedPaths: ['/mine', '/profile', '/settings'],
      guestPaths: ['/login', '/register'],
    },
  },
})

useLoginCheck() 主要服务于业务侧细粒度引导（具体操作前检查），不是 middleware 替代品。

注意事项

必须 await，否则后续业务在登录未完成时就跑了（Rule UL-001）—— 返回 Promise<boolean>（true=已登录 / false=未登录且已跳转登录页或已弹登录框）。不 await 会导致拿到 null userInfo、向后端发未认证请求、或出现「先报错后跳登录页」的怪现象。标准写法 if (!(await useLoginCheck())) return。
TS 的 no-floating-promises 只兜住一部分 —— 条件分支里的嵌套调用、忘记给外层函数加 async 等场景仍会漏，写的时候自己多看一眼。
它与 useLoginDialog() 语义完全不同 —— 本函数做登录判断（已登录直接放行）；useLoginDialog() 只切弹窗显隐、不判断（见 Rule ULD-001）。要「未登录才拦 + 等结果」一律用本函数。