Nuxt 3 路由中间件用法与常见踩坑备忘

发布于2026-11-22 12:47 阅读12次 记录 Nuxt 3 路由中间件的三种形式与基本写法,并总结在中间件里直接访问浏览器对象、重定向漏写 return、全局中间件过于重量级、认证状态用普通 ref 存储导致 SSR 阶段丢失等高频坑,附执行顺序与服务端客户端双向调试思路。
# Nuxt 3 路由中间件用法与常见踩坑备忘
Nuxt 3 的中间件(middleware)是在页面渲染前执行的一段逻辑,常用来做登录校验、权限判断、重定向。它和普通 Vue 路由守卫不是一个东西,本文记录它的三种写法与几个真实踩过的坑。
## 一、中间件的三种形式
Nuxt 3 里中间件按作用范围分三类:
- **匿名(内联)中间件**:直接写在页面组件的 `definePageMeta` 里,只对该页生效
- **命名中间件**:放在 `middleware/` 目录下,可在多个页面按需引用
- **全局中间件**:文件名带 `.global` 后缀,自动对所有路由生效
## 二、基本写法
命名中间件 `middleware/auth.ts`:
```ts
export default defineNuxtRouteMiddleware((to, from) => {
const token = useCookie('token')
if (!token.value && to.path !== '/login') {
return navigateTo('/login')
}
})
```
页面里引用:
```vue
<script setup>
definePageMeta({ middleware: 'auth' })
</script>
```
## 三、四个高频坑
> **坑 1:在中间件里直接用 window / document**
> 中间件会在服务端也执行一次(SSR),这时没有浏览器环境,直接访问 `window` 会报错。要用 `import.meta.client` 判断,或把浏览器相关逻辑放进 `onMounted`。
> **坑 2:重定向没有 return**
> 写 `navigateTo('/login')` 却忘了 `return`,Nuxt 不会中断当前中间件的执行,页面可能继续渲染。务必 `return navigateTo(...)`。
> **坑 3:全局中间件过于重量级**
> 全局中间件每个路由切换都会跑,里面不要放昂贵的同步计算或每次都发请求,否则页面切换明显卡顿。能缓存的状态就缓存。
> **坑 4:认证状态用普通 ref 存**
> 用普通 `ref` 存登录态,刷新页面就丢了。要用 `useCookie` 或配合持久化 store,SSR 阶段才能拿到正确状态,避免"登录了还被踢回登录页"。
## 四、执行顺序与调试
同名中间件按引用顺序执行,全局中间件先于页面中间件。调试时在中间件里加 `console.log`,同时看服务端终端和浏览器控制台——因为 SSR 阶段日志只出现在服务端。
掌握这几点,登录拦截、角色权限这类需求基本能一次写对,不至于在服务端客户端两边反复横跳。