您正在浏览 Nuxt 2 文档。前往 Nuxt 3 文档， 或了解更多关于 Nuxt 2 长期支持。

文件系统路由

Nuxt 根据 pages 目录中 Vue 文件的树形结构自动生成 vue-router 配置。在 pages 目录中创建 .vue 文件后，无需任何特殊配置即可实现基本路由。

有时您可能需要创建动态路由或嵌套路由，或者需要更精细地配置路由属性。本章将介绍充分利用路由所需了解的一切。

Nuxt 无需配置即可自动进行代码分割。
使用 NuxtLink 组件 在页面间导航。
<template>
  <NuxtLink to="/">Home page</NuxtLink>
</template>

路由基础

以下目录结构：

pages/
--| user/
-----| index.vue
-----| one.vue
--| index.vue

将自动生成：

router: {
  routes: [
    {
      name: 'index',
      path: '/',
      component: 'pages/index.vue'
    },
    {
      name: 'user',
      path: '/user',
      component: 'pages/user/index.vue'
    },
    {
      name: 'user-one',
      path: '/user/one',
      component: 'pages/user/one.vue'
    }
  ]
}

动态路由

有时无法确定路由名称，例如从 API 获取用户或博客文章列表时。我们称之为动态路由。要创建动态路由，需要在 .vue 文件名或目录名前添加下划线（_）。文件或目录可以任意命名，但必须带有下划线前缀。

以下目录结构：

pages/
--| _slug/
-----| comments.vue
-----| index.vue
--| users/
-----| _id.vue
--| index.vue

将自动生成：

router: {
  routes: [
    {
      name: 'index',
      path: '/',
      component: 'pages/index.vue'
    },
    {
      name: 'users-id',
      path: '/users/:id?',
      component: 'pages/users/_id.vue'
    },
    {
      name: 'slug',
      path: '/:slug',
      component: 'pages/_slug/index.vue'
    },
    {
      name: 'slug-comments',
      path: '/:slug/comments',
      component: 'pages/_slug/comments.vue'
    }
  ]
}
名为 users-id 的路由路径为 :id?，表示该 :id 是可选的。如果要使其必填，请在 users/_id 目录中创建 index.vue 文件。
Nuxt >= v2.13 安装了爬虫，会爬取链接标签并根据这些链接生成动态路由。但如果有没有链接的页面（如秘密页面），则需要手动生成这些动态路由。

本地访问路由参数

在本地页面或组件中，可以通过引用 this.$route.params.{parameterName} 访问当前路由参数。例如，如果有动态用户页面（users/_id.vue）并想访问 id 参数来加载用户或进程信息，可以访问变量：this.$route.params.id

嵌套路由

Nuxt 允许使用 vue-router 的子路由创建嵌套路由。要定义嵌套路由的父组件，需要创建与包含子视图的目录同名的 Vue 文件。

不要忘记在父组件（.vue 文件）中包含 NuxtChild 组件 。

以下目录结构：

pages/
--| users/
-----| _id.vue
-----| index.vue
--| users.vue

将自动生成：

router: {
  routes: [
    {
      path: '/users',
      component: 'pages/users.vue',
      children: [
        {
          path: '',
          component: 'pages/users/index.vue',
          name: 'users'
        },
        {
          path: ':id',
          component: 'pages/users/_id.vue',
          name: 'users-id'
        }
      ]
    }
  ]
}

动态嵌套路由

虽然不常用，但 Nuxt 支持在动态父路由中嵌套动态子路由。

以下目录结构：

pages/
--| _category/
-----| _subCategory/
--------| _id.vue
--------| index.vue
-----| _subCategory.vue
-----| index.vue
--| _category.vue
--| index.vue

将自动生成：

router: {
  routes: [
    {
      path: '/',
      component: 'pages/index.vue',
      name: 'index'
    },
    {
      path: '/:category',
      component: 'pages/_category.vue',
      children: [
        {
          path: '',
          component: 'pages/_category/index.vue',
          name: 'category'
        },
        {
          path: ':subCategory',
          component: 'pages/_category/_subCategory.vue',
          children: [
            {
              path: '',
              component: 'pages/_category/_subCategory/index.vue',
              name: 'category-subCategory'
            },
            {
              path: ':id',
              component: 'pages/_category/_subCategory/_id.vue',
              name: 'category-subCategory-id'
            }
          ]
        }
      ]
    }
  ]
}

未知的动态嵌套路由

如果 URL 结构的深度未知，可以使用 _.vue 文件动态匹配嵌套路径。这将处理与更具体路由不匹配的请求。

以下目录结构：

pages/
--| people/
-----| _id.vue
-----| index.vue
--| _.vue
--| index.vue

将处理以下请求：

/ -> index.vue
/people -> people/index.vue
/people/123 -> people/_id.vue
/about -> _.vue
/about/careers -> _.vue
/about/careers/chicago -> _.vue
404 页面的处理取决于 _.vue 页面的逻辑。

扩展路由器

有几种方式可以扩展 Nuxt 的路由：

router 属性

可以使用 router 属性自定义 Nuxt 的路由器（vue-router）。

nuxt.config.js
export default {
  router: {
    // 自定义 Nuxt 路由器
  }
}

Base：

应用程序的基础 URL。例如，如果整个单页应用程序在 /app/ 下提供服务，则 base 应设置为 /app/。

extendRoutes

有时您可能想要扩展 Nuxt 生成的路由，可以通过 extendRoutes 选项实现。

添加自定义路由的示例：

nuxt.config.js
export default {
  router: {
    extendRoutes(routes, resolve) {
      routes.push({
        name: 'custom',
        path: '*',
        component: resolve(__dirname, 'pages/404.vue')
      })
    }
  }
}

如果要对路由排序，可以使用 @nuxt/utils 的 sortRoutes(routes) 函数：

nuxt.config.js
import { sortRoutes } from '@nuxt/utils'
export default {
  router: {
    extendRoutes(routes, resolve) {
      // 在此添加路由...

      // 然后排序
      sortRoutes(routes)
    }
  }
}
路由的 schema 应遵循 vue-router 的 schema。
添加使用命名视图 的路由时，不要忘记为对应的命名 components 添加 chunkNames。
nuxt.config.js
export default {
  router: {
    extendRoutes(routes, resolve) {
      routes.push({
        path: '/users/:id',
        components: {
          default: resolve(__dirname, 'pages/users'), // 或 routes[index].component
          modal: resolve(__dirname, 'components/modal.vue')
        },
        chunkNames: {
          modal: 'components/modal'
        }
      })
    }
  }
}

fallback

控制当浏览器不支持 history.pushState 但模式设置为 history 时，路由器是否应回退到 hash 模式。

mode

配置路由模式，由于服务端渲染的原因，不建议更改此设置。

parseQuery / stringifyQuery

提供自定义查询字符串解析/序列化函数。

routeNameSplitter

有时您可能想更改 Nuxt 使用的路由名称分隔符，可以通过配置文件中的 routeNameSplitter 选项实现。假设有页面文件 pages/posts/_id.vue，Nuxt 会按程序生成路由名称，此例中为 posts-id。将 routeNameSplitter 配置更改为 / 后，名称将变为 posts/id。

nuxt.config.js
export default {
  router: {
    routeNameSplitter: '/'
  }
}

scrollBehavior

scrollBehavior 选项允许您定义页面间导航时滚动位置的自定义行为，每次页面渲染时都会调用此方法。

v2.9.0 起可用：

可以使用文件覆盖路由器的 scrollBehavior，此文件应放置在 app 文件夹中。

~/app/router.scrollBehavior.js

强制所有路由滚动到顶部的示例：

app/router.scrollBehavior.js
export default function (to, from, savedPosition) {
  return { x: 0, y: 0 }
}

trailingSlash

v2.10 起可用：

如果将此选项设置为 true，所有路由末尾都会添加斜杠。如果设置为 false，则会移除斜杠。

nuxt.config.js
export default {
  router: {
    trailingSlash: true
  }
}
不要在没有准备的情况下设置此选项，需要进行彻底测试。如果将 router.trailingSlash 设置为 undefined（默认值）以外的值，另一个路由将停止工作。因此 301 重定向应正确进行，内部链接需要正确适配。如果将 trailingSlash 设置为 true，则只有 example.com/abc/ 有效，example.com/abc 无效。设置为 false 时则相反。
Edit this page on GitHub Updated at Tue, Apr 14, 2026