通过 100 多个技巧学习 Nuxt！
55.5K

中间件

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

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

有三种路由中间件

  1. 匿名（或内联）路由中间件直接在页面中定义。
  2. 命名路由中间件，放置在 middleware/ 中，并在页面上使用时通过异步导入自动加载。
  3. 全局路由中间件，放置在带有 .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
()
  }
  // 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) - 使用错误拒绝当前导航
在 文档 > API > Utils > Navigate To 中阅读更多内容。
在 文档 > API > Utils > Abort Navigation 中阅读更多内容。
我们建议使用上面的助手函数来执行重定向或停止导航。 vue-router 文档中描述的其他可能的返回值可能会起作用，但将来可能会有重大更改。

中间件顺序

中间件按以下顺序运行

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

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

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 前缀单个数字的原因。

中间件何时运行

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

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

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 来检查是否正在处理错误。

动态添加中间件

可以使用 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 路由中间件将会被运行。

在 文档 > 示例 > 路由 > 中间件 中阅读和编辑一个实时示例。

在构建时设置中间件

你可以在 pages:extend 钩子中添加命名的路由中间件，而不是在每个页面上使用 definePageMeta。

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 */ true) {
            
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
)
    }
  }
})

布局

Nuxt 提供了一个布局框架，可以将常见的 UI 模式提取到可重用的布局中。

模块

使用 modules/ 目录自动注册应用程序中的本地模块。