其中配置对象的属性 runtimeConfig 可以为 Nuxt 项目设置一些全局可及的变量 global accessible，该属性的值是一个对象，以键值对的形式定义了变量名和它相应的值。

export default defineNuxtConfig({
  runtimeConfig: {
    // 以下属性只能在服务端访问
    // 所以也称为 private key
    apiSecret: '123',
    public: {
      // 以下属性在服务端或客户端都可以访问
      apiBase: '/api'
    }
  }
})

它们就相当于环境变量 environment variable，可以在 .env 文件中设置相应的环境变量（全大写，以 NUXT 为前缀，以下划线 _ 拼接单词），覆盖相应的变量值。

所以可以先在 runtimeConfig 对象中先「预留」需要使用的字段，但是属性值以空字符串等作为默认值，再在部署项目的平台上设置环境变量，设置「真实」的变量值

# 环境变量 NUXT_API_SECRET
# 它所覆盖的是 runtimeConfig 对象的属性 apiSecret
# 所以构建 Nuxt 项目时，该属性最终的值是 345
NUXT_API_SECRET=345

在项目中通过方法 useRuntimeConfig() 获取该对象，该组合式 API 只在 setup() 函数和生命周期相关的钩子函数中可用。

如果在浏览器访问 runtimeConfig，正如其名此时它是运行时的配置项，可修改更新（但是在服务端访问 runtimeConfig 则为只读对象）

<script setup>
const runtimeConfig  = useRuntimeConfig()
console.log(runtimeConfig.public.apiBase) // '/api'
if (process.server) {
  // 只有在服务端才可以访问 apiSecret 属性
  console.log('API secret:', runtimeConfig .apiSecret)
}
</script>

Nuxt 默认只扫描 components 目录，将里面的文件注册为组件

可以在配置文件 📄 nuxt.config.ts 的属性 components 添加其他目录，或设置扫描的方式

export default defineNuxtConfig({
  // 设置存放组件的目录
  // 属性值是数组，每一个元素就是一个需要自动扫描的目录
  components: [
    // 以对象的方式，添加一个子目录
    {
      // 需要添加的目录的路径
      path: '~/anotherComponents',
      // 该目录里的组件的名称都添加特定的前缀
      prefix: 'Special'
    },
    // 或以字符串的方式，添加一个子目录
    // 直接给出目录的路径
    '~/components' // 这是默认目录
  ]
})

[
  ".js",
  ".jsx",
  ".mjs",
  ".ts",
  ".tsx",
  ".vue"
]

export default defineNuxtConfig({
  components: [
    {
      path: '~/components',
      // 只扫描该目录下的 .vue 文件
      extensions: ['.vue'],
    }
  ]
})

组件的名称一般和文件名称相同，所以推荐 components 目录里的文件命名方式采用 Pascal Case 大驼峰命名法，如 ImageView.vue

但是如果文件是内嵌在子目录里，则所组件的名称会有各层级的目录名称和文件名称拼接而成

📂 components
 |-- 📁 base
      |-- 📁 foo
           |-- 📄 Button.vue

以上示例文件 Button.vue 会注册为 <BaseFooButton /> 组件

如果不想基于文件所在的目录的层级结构来命名组件，可以通过属性 pathPrefix 来取消这个默认行为

export default defineNuxtConfig({
  components: [
    {
      path: '~/components',
      // 目录路径不会成为组件名的一部分
      pathPrefix: false,
    },
  ],
});

例如 ~/components/Some/MyComponent.vue 文件最终所对应的组件名称是 <MyComponent>（而不是 <SomeMyComponent>）

export default defineNuxtConfig({
  components: [
    {
      path: '~/components/special-components', // 子目录
      prefix: 'Special'
    },
    '~/components'
  ]
})

对于自动导入的组件，只有在模板中以 <componentName> 形式引用才可以被 Nuxt 识别 ❓ 由于并没有显式导入组件实例，如果需要使用动态组件 <component :is="componentA" />（其中 componentA 是组件实例）则还需要借助一个工具函数 resolveComponent()

<template>
  <component :is="clickable ? MyButton : 'div'" />
</template>

<script setup>
// 使用方法 `resolveComponent(componentName)` 获取一个实例
// 参数 componentName 是字符串，组件的名称
const MyButton = resolveComponent('MyButton')
</script>

export default defineNuxtConfig({
  components: {
    global: true, // 将该目录里的组件进行全局注册
    dirs: ['~/components']
  },
})

只需要在组件名称之前添加 Lazy 即可实现组件的动态导入/按需加载/懒加载 lazy-loading

如果组件并不是页面必须的，则可以让组件采用懒加载的方式，在满足特定的条件时才加载它，可以优化页面的 JavaScript bundle size 代码打包的大小，加快首次打开页面的速度

<template>
  <div>
    <h1>Mountains</h1>
    <!-- 该组件的原名是 MountainsList -->
    <LazyMountainsList v-if="show" />
    <button v-if="!show" @click="show = true">Show List</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      show: false
    }
  }
}
</script>

Nuxt 提供了一个内置组件 <ClientOnly> 以指定仅在客户端渲染的代码块

<template>
  <div>
    <Sidebar />
    <ClientOnly>
      <!-- this component will only be rendered on client-side -->
      <Comments />
    </ClientOnly>
  </div>
</template>

该内置组件提供了一个 Prop fallbackTag 用于设置在服务端渲染时，该内置组件会渲染为哪一个 HTML 标签。

也提供了一个名为 fallback 的插槽，用于设置该组件在服务端渲染哪些内容（作为一种回退策略），等到页面在浏览器渲染出来时，会用「真实」的内容替换该插槽。

<template>
  <div>
    <Sidebar />
    <!-- This renders the "span" element on the server side -->
    <ClientOnly fallbackTag="span">
      <!-- this component will only be rendered on client side -->
      <Comments />
      <template #fallback>
        <!-- this will be rendered on server side -->
        <p>Loading comments...</p>
      </template>
    </ClientOnly>
  </div>
</template>

另外也可以为文件的名称添加 .client （其中 . 点是与前面的文件名分隔，该后缀并不作为组件名称的一部分），则 Nuxt 会自动将组件转换为 client-only，表示该组件仅在前端渲染

client-only 组件要等到 mounted 到页面后才进行渲染，所以如果要访问该组件的模板的渲染结果 access the template，逻辑代码需要编写在 onMounted 钩子函数中

而且为了保证组件渲染后才进行访问，还要在钩子函数的回调函数中 💡 使用 await nextTick() 对逻辑代码进行包裹

📂 components
 |-- 📄 Comments.client.vue

<template>
  <div>
    <!-- this component will only be rendered on client side -->
    <Comments />
  </div>
</template>

与 .client 相对应，也可在添加 .server 后缀，但是目前默认情况下，添加了该后缀的组件是可以在前后端通用的

其实可以将添加了 .server 后缀的组件设置为「标准的」仅在后端渲染，需要在配置文件 nuxt.config.ts 中设置属性 experimental.componentIslands

export default defineNuxtConfig({
  experimental: {
    componentIslands: true
  }
})

server-only 组件只会在后端渲染，当组件的 Props 更新时，会触发一个网络请求，让后端根据新的数据重新渲染组件，最后采用 in-place 原位更新的方式更新页面上相应的 HTML 元素

📂 components
 |-- 📄 HighlightedMarkdown.server.vue

<template>
  <div>
    <!--
      this will automatically be rendered on the server,
      meaning your markdown parsing + highlighting libraries
      are not included in your client bundle.
     -->
    <HighlightedMarkdown markdown="# Headline" />
  </div>
</template>

如果在项目中分别针对客户端和后端创建了同名的两个组件，则它们需要遵顼一定的规则

📂 components
 |-- 📄 Comments.client.vue <!-- 在前端采用该组件 -->
 |-- 📄 Comments.server.vue <!-- 在后端采用该组件 -->

其中 client-only 组件需要在初次加载时和 server-only 组件渲染的结果相同，这样页面才可以在前端 hydrate 渲染成功，否则会发生 hydration mismatch 错误

Nuxt 提供了一个内置组件 <DevOnly> 以指定仅在开发环境中渲染的代码块，而在生成环境中会被 tree-shaken 抛弃掉，不会在包含在最后的打包结果中

<template>
  <div>
    <Sidebar />
    <DevOnly>
      <!-- this component will only be rendered during development -->
      <LazyDebugBar />
    </DevOnly>
  </div>
</template>

Nuxt 提供了一个内置组件 <NuxtClientFallback> 作为一个容器，以捕获它（默认插槽中）所包含的内容在 SSR 服务端渲染时抛出错误（该组件的内容无法渲染） ❓ 并通过一个 Prop fallback-tag 设置该组件渲染为哪一个 HTML 标签作为「候补内容」

<template>
  <div>
    <Sidebar />
    <!-- this component will be rendered on client-side -->
    <NuxtClientFallback fallback-tag="span">
      <Comments />
      <BrokeInSSR />
    </NuxtClientFallback>
  </div>
</template>

嵌套路由所对应的页面就像积木一样，通过每一层路由所对应的组件嵌套搭建而成的，即子组件会内嵌到其父组件的特定位置，这个位置就是通过在父组件中使用内置组件 <NuxtPage/> 来指定的

📂 pages
 |-- 📂 parent
 |    |-- 📄 child.vue
 |-- 📄parent.vue

Nuxt 根据以上的文件系统生成以下的嵌套路由

[
  {
    path: '/parent', // 对应的路由是 /parent
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child', // 对应的路由是 /parent/child
        component: '~/pages/parent/child.vue',
        name: 'parent-child'
      }
    ]
  }
]

为了展示出 child.vue 需要在 pages/parent.vue 的模板中使用内置组件 <NuxtPage /> 指明位置

<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>

Nuxt 除了可以基于该目录的文件结构来构建页面路由，还可以基于文件名来创建特别的路由

在目录或文件名称中使用方括号 [paraName] 来创建动态路由，即页面可以匹配一系列 URL（动态路由）。其中方括号中就是动态路由的参数变量，可以通过页面的路由对象 route 的相应属性来获取参数值

📂 pages
 |-- 📄 index.vue
 |-- 📂 users-[group]
      |-- 📄 [id].vue

<!-- 该页面可以匹配一系列 URL（动态路由） -->
<template>
  <!-- 使用选项式 Option API 显示当前路由的参数 group 和 id 的值 -->
  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
</template>

<script setup>
// 使用组合式 API 来访问该页面的路由对象
const route = useRoute()

if (route.params.group === 'admins' && !route.params.id) {
  console.log('Warning! Make sure user is authenticated!')
}
</script>

例如当用户访问的 URL 为 /users-admins/123 时，则生成的页面为

<p>admins - 123</p>

还可以设置一个文件名称的形式为 [...slug].vue 格式的页面（...slug 就类似于 JS 解构语法），它会匹配所有的路由，参数 slug 是将嵌套路由的各部分解构为一系列的参数所构成一个数组

<template>
  <p>{{ $route.params.slug }}</p>
</template>

如果用户访问 URL 为 /hello/world 则渲染出的页面如下

<p>["hello", "world"]</p>

以上说到的页面元信息 Page Metadata 是为了给页面/路由对象提供一些额外信息的，通过 definePageMeta() 方法进行设置。这些信息可以在页面的路由对象的属性 route.meta 访问得到。

<script setup>
definePageMeta({
  title: 'My home page'
})

const route = useRoute()

console.log(route.meta.title) // My home page
</script>

<script setup>
import { someData } from '~/utils/example'

const title = ref('')

definePageMeta({
  title, // ❌ This will create an error
  someData // ✅ can access this data
})
</script>

可以为页面添加任意的元信息，其中有一些元信息属性是具有特定的含义

• keepalive 属性：如果将其属性值设置为 true，则 Nuxt 会为页面组件外包裹一个 Vue 内置组件 <keepAlive>，在路由切换时缓存该页面的状态，切换回来时可以看到页面的状态数据是被保留的。
  该属性值还可以是一个对象，会作为 Props 传递给 <KeepAlive> 以便对该组件进行更详细的配置。
  可以在配置文件 nuxt.config.ts 的属性 app.keepalive 为该内置组件设置默认的 Props 参数
  提示

  如果在嵌套路由中想保留子组件的状态，也可以直接在内置组件设置相应的属性 <NuxtPage keepalive />

• key 属性：该页面组件的唯一标识符
• layout 属性：设置该页面使用哪个布局模板，也可以设置为 false 表示不使用任何布局模板（但依然可以在页面中通过 <NuxtLayout> 组件来应用模板）。具体参考本文的 layouts 目录部分
• middleware 属性：为该页面设置专属的路由中间件。具体参考本文的 middleware 目录
• layoutTransition 属性：为该页面设置布局更改的过渡动效
• pageTransition 属性：为该页面设置页面切换的过渡动效

• alias 属性：为该页面设置路由别名，这样就可以通过不同的 URL 来访问该页面。该属性值可以是字符串或数组，具体可以参考 Vue Router 的官方文档
• name 属性：为该页面所对应的路由设置名称（需要是唯一值，作为该路由的标识符）。在（编程式）导航时，用名称来指代操作路径较长的路由，可以便于操作。具体可以参考 Vue Router 的官方文档
• path 属性：为页面设置所匹配的路由路径，而不采用由文件和目录名称所默认构成的路由路径。支持采用正则表达式构建更复杂的匹配模式，具体可以参考 Vue Router 的官方文档

除了在地址栏手动输入 URL 来访问相应的页面，Nuxt 还提供一个内置组件 <NuxtLink to="urlPath" /> 来生成链接以供用户点击触发路由导航

<template>
  <!-- 链接到主页 -->
  <NuxtLink to="/">Home page</NuxtLink>
</template>

此外 Nuxt 还提供 navigateTo() 方法来实现编程式导航 programmatic navigation

这是一个异步函数，如果希望在完成导航后执行其他操作，需要使用 async-await 语法或链式调用

<script setup>
const router = useRouter();
const name = ref('');
const type = ref(1);

function navigate(){
  return navigateTo({
    path: '/search',
    query: {
      name: name.value,
      type: type.value
    }
  })
}
</script>

这个目录下的组件只是提供了特定的页面布局，所以模板中还需要包含插槽 <slot/>（至少一个），以便将具体的页面内容插入到其中

需要在该目录下应该创建一个名为 default.vue 的文件，以便让页面具有默认布局可以使用

<template>
  <div>
    <AppHeader />
    <slot />
    <AppFooter />
  </div>
</template>

也可以设置多个具名插槽，实现更复杂的布局

<template>
  <div>
    Some shared layout content:
    <!-- 具名插槽 header -->
    <slot name="header">
      header slot content for title
    </slot>
    <!-- 默认插槽 -->
    <slot />
  </div>
</template>

在使用布局时，如果项目采用单页面模式，即项目中只有 app.vue 文件，则需要在其中添加 Nuxt 的内置组件 <NuxtLayout> 将布局应用到页面上

<template>
  <NuxtLayout>
    some page content
  </NuxtLayout>
</template>

<template>
  <div>
    <NuxtPage />
  </div>
</template>

如果项目采用多页面模式，即在目录 pages 下创建页面，则这些页面会采用默认布局

一般情况下采用默认布局 layouts/default.vue，如果需要采用其他布局，可以进行如下设置

如果需要为 app.vue 设置特定的布局模板，可以通过 <NuxtLayout name="layoutName"> 来配置，则相应的布局模板就会按需自动异步导入 asynchronous import

<template>
  <NuxtLayout name="custom">
    <!-- 将指定的内容插入到布局模板的默认插槽中 -->
    Hello world!
  </NuxtLayout>
</template>

而对于 📁 pages 目录中的文件，则可以通过页面元信息 page metadata 设置使用哪个布局模板

<script setup>
// 通过设置页面元信息来使用相应的布局模板
definePageMeta({
  layout: "custom",
});
</script>

如果希望 📁 pages 目录下的页面也采用 <NuxtLayout name="layoutName"> 的方式来设置布局模板，则需要先将页面元信息的 layout 属性设置为 false

<script setup>
// 将页面元信息设置为 false
definePageMeta({
  layout: false,
});
</script>

<template>
  <NuxtLayout name="custom">
    <template #header> Some header template content. </template>
    The rest of the page
  </NuxtLayout>
</template>

<script setup>
// 路由对象
const route = useRoute()
function enableCustomLayout () {
  // 通过改变该页面路由对象的相应属性来切换页面的布局
  route.meta.layout = "custom"
}

// 通过 `definePageMeta()` 设置该页面元信息
// 将属性 layout 设置为 false 表示不采用默认的布局模板
definePageMeta({
  layout: false,
});
</script>
<template>
  <div>
    <!-- 点击该按钮，调用相应的方法，更改页面所采用的布局 -->
    <button @click="enableCustomLayout">Update layout</button>
  </div>
</template>

通过函数 defineNuxtRouteMiddleware(handler) 创建一个路由中间件（具名路由中间件或全局路由中间件）

该函数 handler(to, from) 接收两个参数

• 第一个参数 to：表示需要导航到的目标页面的路由对象
• 第二个参数 from：表示当前页面的路由对象

Nuxt 根据处理函数 handler() 的返回值来实现不同的导航行为，包括放行导航、重定向、阻止导航

该函数最后可以返回以下类型的值

• 无返回值：守卫放行。进入下一个路由中间件，或执行路由导航
• 返回 navigateTo(route) 函数：它是 Nuxt 提供的 helper 工具函数，用于跳转到给定的路由 route
  提示

  该方法也可以在前端直接调用以触发路由导航，具体用法可以参考另一篇笔记《Nuxt 3 API》关于 navigateTo 的部分

• 返回 abortNavigation(err) 函数：它是 Nuxt 提供的 helper 工具函数，用于阻止路由导航，可以传入一个（可选）参数 err 以便同时抛出错误信息

// 定义一个路由中间件
export default defineNuxtRouteMiddleware((to, from) => {
  // 根据目标路由的参数 id 的值
  // 决定页面导航的行为
  if (to.params.id === '1') {
    // 如果该参数值为 1
    // 则阻止页面导航
    return abortNavigation()
  }
  // 如果该参数值不为 1
  // 则导航到首页
  return navigateTo('/')
})

还可以通过的 helper 函数 addRouteMiddleware(middle-name, handler(to, from), configObj) 为应用动态添加 dynamically一个具名路由中间件（默认）或全局路由中间件（在该函数的第二个参数对象中设置 { global: true}）。

这种方法一般在插件中使用

// 一般用于插件中
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')
  })
})

export default defineNuxtRouteMiddleware(to => {
  // 如果页面是在服务端进行渲染的
  // 则直接返回/放行，不执行该路由中间件的余下代码
  if (process.server) return
  // 如果页面是在前端被访问时
  // 则直接返回/放行，不执行该路由中间件的余下代码
  if (process.client) return
  // or only skip middleware on initial client load
  const nuxtApp = useNuxtApp()
  // 如果页面是在客户端首次加载
  // 则直接返回/放行，不执行该路由中间件的余下代码
  if (process.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) return
})

Nuxt 提供了 3 种类型的路由中间件，以便设置不同等级（守卫范围不同）的路由守卫 route guard：

• 匿名/内联路由中间件 Anonymous/Inline Route Middleware：直接在特定页面的元信息中进行创建
  pages/example.vue

  vue

  <script setup>
  definePageMeta({
    // This is an example of inline middleware
    middleware: () => {
      console.log('Strictly forbidden.')
      // 返回 false 表示阻止路由导航
      // 所以无法进入该页面
      return false
    }
  })
  </script>
  

• 具名路由中间件 Named Route Middleware：在 📁 middleware/ 目录中创建，然后在（需应用该路由守卫的）页面的元信息中进行设置。
  在导航到该页面时，该路由守卫代码就会异步加载
  注明

  具名路由中间件的名称会根据文件名而定，而且会通过 kebab-case 短横线分隔命名法进行标准化，例如在名为 someMiddleware 文件中所定义的路由中间件，在使用/引用它时，对应的名称是 some-middle

  
  先定义一个路由中间件
  middleware/auth.ts

  ts

  // 该路由中间件的作用是鉴别访问页面的用户是否已经拥有相应的权限
  export default defineNuxtRouteMiddleware((to, from) => {
    // isAuthenticated() 方法表示在其他文件中定义的工具函数，用于鉴权
    // 它返回一个布尔值，以表示用户是否已经获取了相应的权限
    // isAuthenticated() is an example method verifying if a user is authenticated
    if (isAuthenticated() === false) {
      // 如果用户没有获取相应的权限，则跳转到登录页面
      return navigateTo('/login')
    }
  })
  

  
  再在页面中应用
  pages/dashboard.vue

  vue

  <script setup>
  definePageMeta({
    middleware: 'auth'
  })
  </script>
  <template>
    <h1>Welcome to your dashboard</h1>
  </template>
  

• 全局路由中间件 Global Route Middleware：在 📁 middleware/ 目录中创建具有 .global 后缀的文件，则在其中所定义的路由中间件会自动应用到所有页面上
  middleware/alwaysRun.global.ts

  ts

  // 全局路由中间件，文件名具有 .global 后缀
  export default defineNuxtRouteMiddleware(() => {
    console.log('running global middleware')
  })
  

Nuxt 会基于 📁 server/api 目录里的文件的层级嵌套结构，创建出相应的服务端路由（拥有 /api 前缀）

// 创建了一个 API '/api/hello'
// 为该服务端 API 设置处理函数
export default defineEventHandler((event) => {
  return {
    api: 'works'
  }
})
// 然后可以在客户端向 API `await $fetch('/api/hello')` 发送请求

此外还可以采用特定的目录或文件名称创建具有特定功能的路由

• 可以在文件名中使用方括号 [] 来创建动态路由
  例如通过文件 server/api/hello/[name].ts 创建了一个动态路由
  server/api/hello/[name

  ts

  // 创建了一个动态路由
  // 这里在服务端为该 API 设置处理函数
  // 通过 event.context.params 获取该动态路由的参数值
  export default defineEventHandler(event => `Hello, ${event.context.params.name}!`)
  // 如果前端端向 API 发送请求 `await $fetch('/api/hello/ben')`
  // 则可以获得的响应值是 `Hello, ben!`
  

• 可以通过 [...] 创建一个匹配所有的 URL 的路由，即通用路由
  例如创建一个文件 server/api/foo/[...].ts 可以响应一系列的请求，譬如（前端）向 /api/foo/bar/baz 所发送的请求
• 如果将请求的方法作为文件名的后缀（用 . 点分隔，例如 .get、.post、.put、.delete 等），可以针对同一个服务端的路由的不同请求方式，设置不同的处理函数
  server/api/test.get.ts

  ts

  // 该处理函数会响应使用 GET 方法向该路由发送过来的请求
  export default defineEventHandler(() => 'Test get handler')
  

  server/api/test.post.ts

  ts

  // 而该处理函数则会响应使用 POST 方法向该路由发送过来的请求
  export default defineEventHandler(() => 'Test post handler')
  

  
  以上例子为 /test 路由设置了两个处理函数，而且分别针对采用 GET 或 POST 方法向该 API 发送请求的情况。而如果使用其他方法方式请求，则会返回 404 错误提示。
  说明

  因为不同的请求方法传递的信息和格式不相同，一般需要设置不同的处理方法。所以 Nuxt 为此场景提出基于特定的文件命名规则，可以十分方便地针对不同的请求方法，设置不同的响应处理方法。

  例如使用 POST 方法发送请求时，一般会发送请求体 request body，可以在路由处理函数中获取到它

  server/api/submit.post.ts

  ts

  // 该服务器路由的处理函数只会响应通过 `POST` 发送的请求
  // 这样在处理函数内就可以安全地使用组合式 API `readBody()` 获取请求体
  // 如果处理函数不对请求方法加以区分
  // 对通过 `GET` 方法发送过来的请求也调用了 `readBody(event)`
  // 则会引起 `405 Method Not Allowed` 的错误。
  export default defineEventHandler(async (event) => {
      // 使用 readBody() 方法获取请求体
      const body = await readBody(event)
      return { body }
  })
  

Nuxt 会基于 📁 server/routes 目录里的文件的层级嵌套结构，创建出相应的服务端路由（不包含 /api 前缀）

// 创建一个 /hello 路由
export default defineEventHandler(() => 'Hello World!')
// 那么在开发环境中，就可以在客户端通过 http://localhost:3000/hello 访问该 API

Nuxt 会将 📁 server/middleware 目录下的文件作为服务器的中间件，它们会在每一个请求进入服务器相应路由前执行，例如对请求进行检查、修改请求内容、记录日志等

// 设置一个中间件
// 其作用是输出每一个请求的目标 url
export default defineEventHandler((event) => {
  console.log('New request: ' + event.req.url)
})

// 设置一个中间件
// 其作用是为每一个请求的内容中添加一个属性 auth
export default defineEventHandler((event) => {
  event.context.auth = { user: 123 }
})

以上 3 个子目录中的文件最后都应该导出一个 defineEventHandle(handler) 函数，以处理来自客户端的相应请求

其中处理函数 handler(event) 的入参是 event 可以是请求对象（如果请求是在前端发出的），也可以表示事件对象（因为在 SSR 服务端渲染时，会由服务器自身发出模拟请求，这时实际上分发的是相应的事件，以触发相应的路由处理函数执行）

处理函数 handler 最后应该返回一个 JSON 对象，或一个 Promise 作为响应，或使用 event.res.end()（作出响应，但没有返回具体的内容）以发送响应

export default defineNitroPlugin((nitroApp) => {
  console.log('Nitro plugin', nitroApp)
})

以下是服务器路由的配置示例，以及一些更高级的处理请求的场景

• 获取请求体
  sever/api/submit.post.ts

  ts

  // 创建一个服务端路由的处理函数
  // 针对使用 POST 方法发过来的请求
  export default defineEventHandler(async (event) => {
      // 因为这个处理函数针对的是 POST 请求
      // 所以该请求里具有请求体 request body
      // 可以使用 h3 库所提供的组合式 API readBody() 来获取请求体
      // 参考 https://github.com/unjs/h3#utilities
      const body = await readBody(event)
      // 返回请求体，作为响应
      return { body }
  })
  // 例如前端对 '/api/submit` 所发送的请求如下（包括请求体）
  // $fetch('/api/submit', { method: 'post', body: { test: 123 } })
  // 则所获得的响应是 { method: 'post', body: { test: 123 } }
  

• 获取请求参数
  server/api/query.get.ts

  ts

  // 创建一个服务端路由的处理函数
  // 针对使用 GEt 方法发过来的请求
  export default defineEventHandler((event) => {
    // 使用 h3 库所提供的组合式 API getQuery() 来获取请求时所带的参数
    // 参考 https://github.com/unjs/h3#utilities
    const query = getQuery(event)
    // 基于请求时所带的参数，构建响应数据
    return { a: query.param1, b: query.param2 }
  })
  // 例如前端使用 GET 方法向 `/api/query?param1=123&param2=456` 发送请求
  // 则所获得的响应是 { a: 123, b: 456 }
  

• 返回流数据（实验性支持）
  server/api/foo.get.ts

  ts

  import fs from 'node:fs'
  import { sendStream } from 'h3'
  
  export default defineEventHandler((event) => {
    return sendStream(event, fs.createReadStream('/path/to/file'))
  })
  

• 重定向
  server/api/foo.get.ts

  ts

  export default defineEventHandler((event) => {
    // 使用组合式 API sendRedirect() 实现重定向
    return sendRedirect(event, '/path/redirect/to', 302)
  })
  

• 存储层：后端引擎 Nitro 提供了一个存储层 storage layer，它可以对接文件存储系统、数据库等数据源，并将不同的数据存储平台抽象为统一的 API，方便在项目中使用
  nuxt.config.ts

  ts

  export default defineNuxtConfig({
    // 在配置文件设置存储层
    nitro: {
      storage: {
        'redis': {
          driver: 'redis',
          /* redis connector options */
          port: 6379, // Redis port
          host: "127.0.0.1", // Redis host
          username: "", // needs Redis >= 6
          password: "",
          db: 0, // Defaults to 0
          tls: {} // tls/ssl
        }
      }
    }
  })
  

  server/api/test.post.ts

  ts

  // 设置一个服务端路由处理函数
  // 用于将前端发过来的数据设置存储到 storage layer 中
  export default defineEventHandler(async (event) => {
    const body = await readBody(event)
    await useStorage().setItem('redis:test', body)
    return 'Data is set'
  })
  

  server/api/test.get.ts

  ts

  // 设置一个服务端路由处理函数
  // 从 storage layer 获取数据
  export default defineEventHandler(async (event) => {
    const data = await useStorage().getItem('redis:test')
    return data
  })
  

• 错误处理
  默认情况下，如果服务端路由正常响应，则返回的状态码 status code 是 200 OK；如果有任何错误被触发，则返回的状态码是 500 Internal Server Error
  如果希望路由处理成功时，返回其他状态码，可以使用工具函数 setResponseStatus() 进行修改
  ts

  // 该路由文件的路径是 server/api/validation/[id].ts
  export default defineEventHandler((event) => {
    setResponseStatus(event, 202)
  })
  

  
  如果希望在发生错误时，返回其他的状态码，以便让前端了解到更详细具体的错误信息，可以使用 createError 来创建错误并抛出
  ts

  // 该服务端路由文件的路径是 server/api/validation/[id].ts
  // 创建一个服务端路由的处理函数
  export default defineEventHandler((event) => {
    const id = parseInt(event.context.params.id) as number
    if (!Number.isInteger(id)) {
      // 如果 id 不是整数就抛出一个自定义的错误
      throw createError({
        statusCode: 400, // 状态码
        statusMessage: 'ID should be an integer', // 错误信息
      })
    }
    return 'All good'
  })
  

export default (req, res) => {
  res.end('Legacy handler')
}