Nuxt.js 自定义路由配置完全指南

凤红令Nathania

于 2025-05-30 09:05:47 发布

阅读量361

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01125/article/details/148324403

Nuxt.js 自定义路由配置完全指南

nuxt The Intuitive Vue Framework. 项目地址: https://gitcode.com/gh_mirrors/nu/nuxt

前言

在 Nuxt.js 项目中，路由系统是基于文件系统自动生成的，这大大简化了开发者的工作流程。然而，实际开发中我们经常需要自定义路由配置以满足特定需求。本文将全面介绍 Nuxt.js 中自定义路由的各种方法，帮助开发者灵活控制应用的路由行为。

基础概念

Nuxt.js 使用 vue-router 作为底层路由引擎，默认情况下会根据 pages 目录结构自动生成路由配置。这种约定优于配置的方式虽然便捷，但 Nuxt 也提供了多种方式来覆盖或扩展默认路由。

自定义路由的四种方法

1. 通过 router.options 配置

这是最推荐的自定义路由方式，可以完全控制路由配置：

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

export default {
  routes: (defaultRoutes) => [
    ...defaultRoutes,
    {
      name: 'custom',
      path: '/custom-path',
      component: () => import('~/pages/custom.vue')
    }
  ],
} satisfies RouterConfig

注意事项：

返回 null 或 undefined 会回退到默认路由
这种方式添加的路由不会自动包含 definePageMeta 中定义的元数据

2. 使用 pages:extend 钩子

在构建时修改扫描到的路由配置：

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

export default defineNuxtConfig({
  hooks: {
    'pages:extend'(pages) {
      // 添加新路由
      pages.push({
        name: 'admin',
        path: '/admin',
        file: '~/pages/admin/dashboard.vue'
      })
      
      // 删除匹配特定模式的路由
      const toRemove = []
      for (const page of pages) {
        if (page.file?.includes('secret')) {
          toRemove.push(page)
        }
      }
      for (const page of toRemove) {
        pages.splice(pages.indexOf(page), 1)
      }
    }
  }
})

3. 开发 Nuxt 模块

对于需要添加大量相关页面的功能，可以创建 Nuxt 模块：

// modules/my-module.ts
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('pages:extend', (pages) => {
      pages.push({
        name: 'module-page',
        path: '/module-path',
        file: '~/modules/my-module/pages/index.vue'
      })
    })
  }
})

4. 通过 nuxt.config 配置

对于简单的 JSON 可序列化选项，可以直接在配置文件中设置：

// nuxt.config.ts
export default defineNuxtConfig({
  router: {
    options: {
      linkActiveClass: 'active-link',
      linkExactActiveClass: 'exact-active-link'
    }
  }
})

高级路由配置

哈希模式 (SPA)

在纯客户端应用中启用哈希路由：

export default defineNuxtConfig({
  ssr: false,
  router: {
    options: {
      hashMode: true
    }
  }
})

平滑滚动行为

为哈希链接启用平滑滚动效果：

export default defineNuxtConfig({
  router: {
    options: {
      scrollBehaviorType: 'smooth'
    }
  }
})

自定义历史记录模式

高级场景下可以完全自定义历史记录实现：

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

export default {
  history: base => import.meta.client ? createMemoryHistory(base) : null
} satisfies RouterConfig