middleware

Nuxt 提供中间件，以便在导航到特定路由之前运行代码。

Nuxt 提供了一个可定制的 路由中间件 框架，你可以在整个应用程序中使用它，非常适合提取你想在导航到特定路由之前运行的代码。

路由中间件分为三种类型

  1. 匿名（或内联）路由中间件直接在页面内定义。
  2. 命名路由中间件，放置在 app/middleware/ 中，在页面中使用时通过异步导入自动加载。
  3. 全局路由中间件，放置在 app/middleware/ 中并带有 .global 后缀，在每次路由更改时运行。

前两种路由中间件可以在 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()
  }
  // In a real app you would probably not redirect every route to `/`
  // however it is important to check `to.path` before redirecting or you
  // might get an infinite redirect loop
  if (to.path !== '/') {
    return navigateTo('/')
  }
})

Nuxt 提供了两个全局可用的辅助函数，可以直接从中间件中返回。

  1. navigateTo - 重定向到给定的路由
  2. abortNavigation - 中止导航，带有可选的错误信息。

与来自 vue-router 的 导航守卫 不同，这里不会传递第三个 next() 参数，并且重定向或路由取消是通过从中间件返回值来处理的。

可能的返回值有：

  • 无（一个简单的 return 或完全不返回）- 不会阻塞导航，并将进入下一个中间件函数（如果有的话），或者完成路由导航
  • return navigateTo('/') - 重定向到给定路径，如果重定向发生在服务器端，会将重定向代码设置为 302 Found
  • return navigateTo('/', { redirectCode: 301 }) - 重定向到给定路径，如果重定向发生在服务器端，会将重定向代码设置为 301 Moved Permanently
  • return abortNavigation() - 停止当前的导航
  • return abortNavigation(error) - 拒绝当前的导航并返回一个错误
阅读更多内容，请参见 Docs > 4 X > API > Utils > Navigate To。
阅读更多内容，请参见 Docs > 4 X > API > Utils > Abort Navigation。
我们建议使用上述辅助函数来执行重定向或停止导航。vue-router 文档中描述的其他可能返回值可能有效，但未来可能会有破坏性变更。

中间件顺序

中间件按以下顺序运行：

  1. 全局中间件
  2. 页面定义的中间件顺序（如果使用数组语法声明了多个中间件）

例如，假设你有以下中间件和组件：

app/middleware/ 目录
-| middleware/
---| analytics.global.ts
---| setup.global.ts
---| auth.ts
pages/profile.vue
<script setup lang="ts">
definePageMeta({
  middleware: [
    function (to, from) {
      // Custom inline middleware
    },
    'auth',
  ],
})
</script>

你可以预期中间件将按以下顺序运行：

  1. analytics.global.ts
  2. setup.global.ts
  3. 自定义内联中间件
  4. 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。

中间件何时运行

如果你的网站是服务器端渲染的（SSR）或预渲染生成的，初始页面的中间件会在页面渲染时执行一次，然后在客户端再次执行。如果你的中间件需要浏览器环境（例如你有一个预渲染的网站、使用了激进的响应缓存，或者想要从本地存储中读取值），这可能会非常有用。

但是，如果你想避免这种行为，你可以这样做：

middleware/example.ts
export default defineNuxtRouteMiddleware((to) => {
  // skip middleware on server
  if (import.meta.server) {
    return
  }
  // skip middleware on client side entirely
  if (import.meta.client) {
    return
  }
  // or only skip middleware on initial client load
  const nuxtApp = useNuxtApp()
  if (import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) {
    return
  }
})

即使你在服务器端的中间件中抛出错误并渲染了错误页面，也是如此。中间件仍然会在浏览器中再次运行。

渲染错误页面是一个完全独立的页面加载过程，这意味着任何注册的中间件都会再次运行。你可以在中间件中使用 useError 来检查是否正在处理错误。

在中间件中访问路由

务必在中间件中使用 to 和 from 参数来访问下一个和上一个路由。在此上下文中，应完全避免使用 useRoute() 组合式函数。在中间件中没有“当前路由”的概念，因为中间件可以中止导航或重定向到不同的路由。在这种情况下，useRoute() 组合式函数总是不准确的。

有时，你可能会调用一个内部使用 useRoute() 的组合式函数，这会触发此警告，即使你的中间件中没有直接调用它。这会导致与上述相同的问题，因此当在中间件中使用函数时，你应该将它们构造成接受路由作为参数的形式。
// @errors: 2304
export default defineNuxtRouteMiddleware((to) => {
  // passing the route to the function to avoid calling `useRoute()` in middleware
  doSomethingWithRoute(to)

  // ❌ this will output a warning and is NOT recommended
  callsRouteInternally()
})

动态添加中间件

可以使用 addRouteMiddleware() 辅助函数（例如在插件内部）手动添加全局或命名路由中间件。

export default defineNuxtPlugin(() => {
  addRouteMiddleware('global-test', () => {
    console.log('this global middleware was added in a plugin and will be run on every route change')
  }, { global: true })

  addRouteMiddleware('named-test', () => {
    console.log('this named middleware was added in a plugin and would override any existing middleware of the same name')
  })
})

示例

目录结构
-| middleware/
---| auth.ts

在你的页面文件中，你可以引用这个路由中间件：

<script setup lang="ts">
definePageMeta({
  middleware: ['auth'],
  // or middleware: 'auth'
})
</script>

现在，在完成到该页面的导航之前，将运行 auth 路由中间件。

在 Docs > 4 X > 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 (/* some condition */ Math.random() > 0.5) {
            page.meta ||= {}
            // Note that this will override any middleware set in `definePageMeta` in the page
            page.meta.middleware = ['named']
          }
          if (page.children) {
            setMiddleware(page.children)
          }
        }
      }
      setMiddleware(pages)
    },
  },
})