middleware
Nuxt 提供中间件以在导航到特定路由之前运行代码。
Nuxt 提供了一个可自定义的 路由中间件 框架，您可以在整个应用程序中使用，适合提取您希望在导航到特定路由之前运行的代码。
路由中间件有三种类型：
- 匿名（或内联）路由中间件，直接在页面内定义。
- 命名路由中间件，放置在
middleware/目录下，并在页面使用时通过异步导入自动加载。 - 全局路由中间件，放置在带有
.global后缀的middleware/目录下，会在每次路由变更时执行。
前两种路由中间件可以在 definePageMeta 中定义。
中间件名称会被规范化为 kebab-case：
myMiddleware 变成 my-middleware。路由中间件在 Nuxt 应用的 Vue 部分运行。尽管名称相似，但它们与在 Nitro 服务器部分运行的 服务端中间件 完全不同。
用法
路由中间件是导航守卫，接收当前路由和目标路由作为参数。
middleware/my-middleware.ts
export default defineNuxtRouteMiddleware((to, from) => {
if (to.params.id === '1') {
return abortNavigation()
}
// 在实际应用中，可能不会把每个路由都重定向到 `/`
// 但是在重定向之前检查 `to.path` 是很重要的，否则可能会导致无限重定向循环
if (to.path !== '/') {
return navigateTo('/')
}
})
Nuxt 提供了两个全局辅助函数，可以直接从中间件返回使用。
navigateTo- 重定向到指定路由abortNavigation- 取消导航，可选传入错误信息。
与 vue-router 的 导航守卫 不同，中间件不会传入第三个 next() 参数，重定向或取消路由通过返回值处理。
可能的返回值包括：
- 什么都不返回（简单的
return或没有返回）- 不阻塞导航，将执行下一个中间件（如果有）或完成路由导航 return navigateTo('/')- 重定向到指定路径，若在服务器端执行重定向，则状态码为302Foundreturn navigateTo('/', { redirectCode: 301 })- 重定向到指定路径，若在服务器端执行重定向，则状态码为301Moved Permanentlyreturn abortNavigation()- 停止当前导航return abortNavigation(error)- 拒绝当前导航，并带有错误
我们推荐使用上述辅助函数来执行重定向或停止导航。其他在 vue-router 文档 中描述的返回值可能有效，但未来存在破坏性变更的风险。
中间件执行顺序
中间件的执行顺序为：
- 全局中间件
- 页面定义的中间件顺序（若使用数组语法声明多个中间件）
例如，假设您有如下中间件和组件：
middleware/ 目录
-| middleware/
---| analytics.global.ts
---| setup.global.ts
---| auth.ts
pages/profile.vue
<script setup lang="ts">
definePageMeta({
middleware: [
function (to, from) {
// 自定义内联中间件
},
'auth',
],
});
</script>
您可以预计中间件执行顺序为：
analytics.global.tssetup.global.ts- 自定义内联中间件
auth.ts
全局中间件排序
默认情况下，全局中间件按文件名的字母顺序执行。
但有时您可能需要指定执行顺序。例如，在上述场景中，可能需要 setup.global.ts 在 analytics.global.ts 之前执行。这时建议给全局中间件文件名添加“字母顺序”数字前缀。
目录结构
-| middleware/
---| 01.setup.global.ts
---| 02.analytics.global.ts
---| auth.ts
如果您不熟悉“字母顺序”排序，请记住文件名是作为字符串排序，而非数字大小。例如，
10.new.global.ts 会排在 2.new.global.ts 之前。这就是示例中单数字前缀带 0 的原因。中间件何时运行
如果您的站点是服务端渲染或静态生成，中间件会在页面首次渲染时执行，然后在客户端再执行一次。如果中间件依赖于浏览器环境（如生成的站点，或缓存响应，或要读取本地存储），这很有用。
但若您想避免此行为，可以这样写：
middleware/example.ts
export default defineNuxtRouteMiddleware(to => {
// 在服务器端跳过中间件
if (import.meta.server) return
// 完全在客户端跳过中间件
if (import.meta.client) return
// 或仅在客户端首次加载时跳过中间件
const nuxtApp = useNuxtApp()
if (import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) return
})
即便您在服务器端中间件中抛出了错误并渲染了错误页，浏览器端仍会再次执行该中间件。
渲染错误页是一次全新的页面加载，意味着注册的中间件会再次运行。您可以在中间件中使用
useError 判断当前是否处理错误。动态添加中间件
您可以使用 addRouteMiddleware() 辅助函数手动添加全局或命名路由中间件，例如在插件中。
export default defineNuxtPlugin(() => {
addRouteMiddleware('global-test', () => {
console.log('此全局中间件是在插件中添加的，将在每次路由变更时运行')
}, { global: true })
addRouteMiddleware('named-test', () => {
console.log('此命名中间件是在插件中添加的，会覆盖同名已存在中间件')
})
})
示例
目录结构
-| middleware/
---| auth.ts
在页面文件中，您可以引用该路由中间件：
<script setup lang="ts">
definePageMeta({
middleware: ["auth"]
// 或者 middleware: 'auth'
})
</script>
导航到该页面前，将执行 auth 路由中间件。
Read and edit a live example in Docs > Examples > Routing > Middleware.
在构建时设置中间件
您可以不在每个页面中使用 definePageMeta，而是在 pages:extend 钩子中添加命名路由中间件。
nuxt.config.ts
import type { NuxtPage } from 'nuxt/schema'
export default defineNuxtConfig({
hooks: {
'pages:extend' (pages) {
function setMiddleware (pages: NuxtPage[]) {
for (const page of pages) {
if (/* 某些条件 */ true) {
page.meta ||= {}
// 注意，这会覆盖页面中 `definePageMeta` 里设置的中间件
page.meta.middleware = ['named']
}
if (page.children) {
setMiddleware(page.children)
}
}
}
setMiddleware(pages)
}
}
})