v3.17
GitHub

自定义路由

在 Nuxt 中，您的路由由 pages 目录中文件的结构定义。不过，由于它在底层使用 vue-router，Nuxt 提供了多种方法来在项目中添加自定义路由。

添加自定义路由

在 Nuxt 中，您的路由由 pages 目录 中文件的结构定义。不过，由于它在底层使用 vue-router，Nuxt 提供了多种方法来在项目中添加自定义路由。

路由配置

使用 路由选项，您可以选择性地覆盖或扩展您的路由，使用一个接受扫描到的路由并返回自定义路由的函数。

如果它返回 null 或 undefined，Nuxt 将回退到默认路由（对修改输入数组非常有用）。

app/router.options.ts
import type { RouterConfig } from '@nuxt/schema'

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions.html#routes
  routes: (_routes) => [
    {
      name: 'home',
      path: '/',
      component: () => import('~/pages/home.vue')
    }
  ],
} satisfies RouterConfig
Nuxt 不会使用您从 routes 函数返回的新路由增强包含在您提供的组件的 definePageMeta 中定义的元数据。如果您希望这样做，您应该使用在 构建时调用的pages:extend 钩子。

页面钩子

您可以使用 pages:extend Nuxt 钩子添加、改变或移除扫描到的路由页面。

例如，防止为任何 .ts 文件创建路由：

nuxt.config.ts
import type { NuxtPage } from '@nuxt/schema'

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (pages) {
      // 添加一个路由
      pages.push({
        name: 'profile',
        path: '/profile',
        file: '~/extra-pages/profile.vue'
      })

      // 移除路由
      function removePagesMatching (pattern: RegExp, pages: NuxtPage[] = []) {
        const pagesToRemove: NuxtPage[] = []
        for (const page of pages) {
          if (page.file && pattern.test(page.file)) {
            pagesToRemove.push(page)
          } else {
            removePagesMatching(pattern, page.children)
          }
        }
        for (const page of pagesToRemove) {
          pages.splice(pages.indexOf(page), 1)
        }
      }
      removePagesMatching(/\.ts$/, pages)
    }
  }
})

Nuxt 模块

如果您计划添加一整套与特定功能相关的页面，您可能想要使用一个 Nuxt 模块。

Nuxt kit 提供几种方式 添加路由：

路由选项

在自定义 vue-router 选项的基础上，Nuxt 提供 额外选项 来定制路由器。

使用 app/router.options

这是指定 路由选项 的推荐方式。

app/router.options.ts
import type { RouterConfig } from '@nuxt/schema'

export default {
} satisfies RouterConfig

通过在 pages:routerOptions 钩子中添加文件，可以添加更多路由器选项文件。数组中的后续项将覆盖前面的项。

在此钩子中添加路由选项文件将启用基于页面的路由，除非设置了 optional，在这种情况下仅在已启用基于页面的路由时应用。
nuxt.config.ts
import { createResolver } from '@nuxt/kit'

export default defineNuxtConfig({
  hooks: {
    'pages:routerOptions' ({ files }) {
      const resolver = createResolver(import.meta.url)
      // 添加一个路由
      files.push({
        path: resolver.resolve('./runtime/app/router-options'),
        optional: true
      })
    }
  }
})

使用 nuxt.config

注意： 仅可配置 JSON 可序列化的 选项：

  • linkActiveClass
  • linkExactActiveClass
  • end
  • sensitive
  • strict
  • hashMode
  • scrollBehaviorType
nuxt.config
export default defineNuxtConfig({
  router: {
    options: {}
  }
})

Hash 模式（SPA）

您可以通过使用 hashMode 配置 在 SPA 模式中启用哈希历史记录。在此模式下，路由在实际 URL 之前使用一个哈希字符（#），并在内部传递。当启用时，URL 从不发送到服务器，并且 不支持 SSR。

nuxt.config.ts
export default defineNuxtConfig({
  ssr: false,
  router: {
    options: {
      hashMode: true
    }
  }
})

哈希链接的滚动行为

您可以选择性地自定义哈希链接的滚动行为。当您将 配置 设置为 smooth 并加载一个具有哈希链接的页面（例如 https://example.com/blog/my-article#comments）时，您会看到浏览器平滑地滚动到该锚点。

nuxt.config.ts
export default defineNuxtConfig({
  router: {
    options: {
      scrollBehaviorType: 'smooth'
    }
  }
})

自定义历史记录（高级）

您可以选择性地使用一个接受基本 URL 并返回历史模式的函数来覆盖历史模式。如果它返回 null 或 undefined，Nuxt 将回退到默认历史。

app/router.options.ts
import type { RouterConfig } from '@nuxt/schema'
import { createMemoryHistory } from 'vue-router'

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions.html
  history: base => import.meta.client ? createMemoryHistory(base) : null /* default */
} satisfies RouterConfig