---
title: "路由"
description: "Nuxt 的文件系统路由会为 pages/ 目录中的每个文件创建一个路由。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/getting-started/routing"
---
# 路由

> Nuxt 的文件系统路由会为 pages/ 目录中的每个文件创建一个路由。

Nuxt 的一项核心功能是文件系统路由。[`app/pages/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages) 目录中的每个 Vue 文件都会创建一个对应的 URL（或路由），用于显示该文件的内容。通过为每个页面使用动态导入，Nuxt 利用代码拆分，仅为请求的路由发送最少量的 JavaScript。

<note>

默认启用代码拆分，且建议大多数应用使用。如果你有特定原因需要改为发送单个 bundle，可以在 [`nuxt.config`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config) 中禁用它：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vite: {
    $client: {
      build: {
        rolldownOptions: {
          output: {
            codeSplitting: false,
          },
        },
      },
    },
  },
})
```

这会将所有 JavaScript 打包到一个文件中。这很少有益处——它通常会增加初始下载量，即使在慢速网络连接下也是如此——因此，只有在你已经测量并确认它对你的场景有帮助时，才应禁用代码拆分。

</note>

## 页面

Nuxt 路由基于 [vue-router](https://router.vuejs.org)，并根据文件名，从 [`app/pages/` 目录](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages) 中创建的每个组件生成路由。

该文件系统路由通过命名约定来创建动态和嵌套路由：

<code-group>

```bash [目录结构]
-| pages/
---| about.vue
---| index.vue
---| posts/
-----| [id].vue
```

```json [生成的路由文件]
{
  "routes": [
    {
      "path": "/about",
      "component": "pages/about.vue"
    },
    {
      "path": "/",
      "component": "pages/index.vue"
    },
    {
      "path": "/posts/:id",
      "component": "pages/posts/[id].vue"
    }
  ]
}
```

</code-group>

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages">



</read-more>

## 导航

[`<NuxtLink>`](https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-link) 组件用于在页面之间创建链接。它会渲染一个 `<a>` 标签，并将 `href` 属性设为页面的路由。应用完成水合后，页面跳转会通过 JavaScript 更新浏览器 URL 来完成。这可以避免整页刷新，并支持动画过渡。

当 [`<NuxtLink>`](https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-link) 在客户端进入视口时，Nuxt 会自动提前预取所链接页面的组件和载荷（生成的页面），从而加快导航速度。

```vue [app/pages/index.vue]
<template>
  <header>
    <nav>
      <ul>
        <li><NuxtLink to="/about">关于</NuxtLink></li>
        <li><NuxtLink to="/posts/1">文章 1</NuxtLink></li>
        <li><NuxtLink to="/posts/2">文章 2</NuxtLink></li>
      </ul>
    </nav>
  </header>
</template>
```

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-link">



</read-more>

## 路由参数

[`useRoute()`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-route) 组合式函数可用于 Vue 组件的 `<script setup>` 块或 `setup()` 方法中，以访问当前路由的详细信息。

```vue [pages/posts/[id].vue]twoslash
<script setup lang="ts">
const route = useRoute()

// 访问 /posts/1 时，route.params.id 的值为 1
console.log(route.params.id)
</script>
```

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-route">



</read-more>

## 路由中间件

Nuxt 提供了一个可自定义的路由中间件框架，可在整个应用中使用，适合抽离导航特定路由前需要执行的代码。

<note>

路由中间件在 Nuxt 应用的 Vue 部分运行。尽管名称相似，但它们与服务器中间件完全不同，服务器中间件运行在应用的 Nitro 服务器部分。

</note>

<important>

路由中间件**不会**在服务器路由（例如 `/api/*`）或其他服务器请求上运行。要将中间件应用于这些请求，请改用[服务器中间件](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/server#server-middleware)。

</important>

路由中间件有三种类型：

1. 匿名（或内联）路由中间件，直接定义在使用它们的页面中。
2. 命名路由中间件，放置在 [`app/middleware/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/middleware) 目录中，并会在页面使用时通过异步导入自动加载。（**注意**：路由中间件名称会规范化为 kebab-case，因此 `someMiddleware` 会变为 `some-middleware`。）
3. 全局路由中间件，放置在 [`app/middleware/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/middleware) 目录中（带有 `.global` 后缀），并会在每次路由变更时自动运行。

`auth` 中间件保护 `/dashboard` 页面的示例：

<code-group>

```ts [middleware/auth.ts]twoslash
function isAuthenticated (): boolean { return false }
// ---cut---
export default defineNuxtRouteMiddleware((to, from) => {
  // isAuthenticated() 是一个示例方法，用于验证用户是否已认证
  if (isAuthenticated() === false) {
    return navigateTo('/login')
  }
})
```

```vue [pages/dashboard.vue]twoslash
<script setup lang="ts">
definePageMeta({
  middleware: 'auth',
})
</script>

<template>
  <h1>欢迎来到你的仪表盘</h1>
</template>
```

</code-group>

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/middleware">



</read-more>

## 路由验证

Nuxt 可通过你希望验证的每个页面中的 [`definePageMeta()`](https://nuxt.zhcndoc.com/docs/4.x/api/utils/define-page-meta) 的 `validate` 属性来验证路由。

`validate` 属性接受当前 `route` 作为参数。你可以返回布尔值来决定该路由是否为该页面的有效路由。返回 `false` 会触发 404 错误。也可以直接返回带有 `statusCode`/`statusMessage` 的对象来自定义错误信息。

如果验证需求更复杂，可以使用匿名路由中间件来实现。

```vue [pages/posts/[id].vue]twoslash
<script setup lang="ts">
definePageMeta({
  validate (route) {
    // 检查 id 是否全由数字组成
    return typeof route.params.id === 'string' && /^\d+$/.test(route.params.id)
  },
})
</script>
```

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/api/utils/define-page-meta">



</read-more>


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.