Nuxt 3 中间件与路由守卫使用指南
发布于2026-09-03 10:11 阅读8次
系统讲解 Nuxt 3 中间件与路由守卫的完整使用方法，涵盖命名中间件、全局中间件、路由元信息配置、登录鉴权、角色权限控制、页面跳转等高频场景，附完整代码示例与常见踩坑点，帮你快速搭建页面权限体系。
# Nuxt 3 中间件与路由守卫使用指南
> 页面需要登录才能访问？不同角色看到不同菜单？Nuxt 3 中间件是路由守卫的核心方案。本文从基础到实战一次讲透。
## 一、中间件是什么
中间件在路由导航前后执行，适合做：
- 登录鉴权（未登录跳登录页）
- 角色权限控制
- 页面访问统计
- 设置页面标题或主题
## 二、创建命名中间件
### 文件：middleware/auth.js
```js
// 登录校验中间件
export default defineNuxtRouteMiddleware((to, from) => {
const token = useCookie("token").value;
if (!token) {
// 未登录跳转到登录页，并记录来源
return navigateTo({
path: "/login",
query: { redirect: to.fullPath }
});
}
});
```
### 文件：middleware/admin.js
```js
// 管理员权限校验
export default defineNuxtRouteMiddleware((to) => {
const user = useCookie("user");
if (user.value?.role !== "admin") {
return abortNavigation("无权访问该页面");
}
});
```
> abortNavigation 会中止导航并显示错误信息，适合无权限场景。
## 三、在页面中使用中间件
```vue
// pages/dashboard.vue：需要登录
<script setup>
definePageMeta({
middleware: "auth"
});
</script>
```
```vue
// pages/admin/index.vue：需要管理员
<script setup>
definePageMeta({
middleware: ["auth", "admin"],
layout: "admin"
});
</script>
```
> 多个中间件按数组顺序依次执行。
## 四、全局中间件
### 文件：middleware/global.js（全局自动生效）
```js
// 所有路由都会经过，注意加 .global 后缀
export default defineNuxtRouteMiddleware((to) => {
console.log("访问路径:", to.fullPath);
});
```
> 文件名带 .global 即全局中间件：middleware/logger.global.js。
## 五、路由元信息配合
用 meta 统一声明权限，避免每个页面写一堆中间件：
```vue
// 在布局或页面中定义 meta
<script setup>
definePageMeta({
requiresAuth: true,
roles: ["admin", "editor"]
});
</script>
```
```js
// 全局中间件中统一处理 meta
export default defineNuxtRouteMiddleware((to) => {
if (!to.meta.requiresAuth) return;
const user = useCookie("user");
if (!user.value) {
return navigateTo("/login");
}
// 角色校验
const roles = to.meta.roles || [];
if (roles.length && !roles.includes(user.value.role)) {
return abortNavigation("没有访问权限");
}
});
```
## 六、服务端渲染下的注意事项
> ⚠️ **坑1：服务端和客户端都执行**
中间件在 SSR 和客户端导航时都会运行。使用 useCookie 等服务端兼容 API，避免 window 报错。
> ⚠️ **坑2：跳转循环**
登录页不要也挂 auth 中间件，否则无限循环跳转。
> ⚠️ **坑3：useState 初始化**
```js
// 服务端设置的用户状态，客户端要能拿到
const user = useState("user", () => null);
if (process.server) {
user.value = await fetchUser();
}
```
## 七、实战场景汇总
- **未登录跳登录**：auth 中间件 + navigateTo
- **无权限提示**：abortNavigation
- **角色区分菜单**：meta.roles + 全局中间件
- **页面访问埋点**：全局中间件记录日志
## 八、小结
中间件是 Nuxt 3 路由控制的核心，掌握命名中间件、全局中间件、meta 配合三种用法，页面权限体系就能轻松搭建。
2
0
文章点评