---
title: "页面"
description: "Nuxt Kit 提供了一组实用工具，帮助你创建和使用页面。你可以使用这些工具来操控页面配置或定义路由规则。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/api/kit/pages"
---
# 页面

> Nuxt Kit 提供了一组实用工具，帮助你创建和使用页面。你可以使用这些工具来操控页面配置或定义路由规则。

## `extendPages`

在 Nuxt 中，路由是根据 `pages` 目录中文件结构自动生成的。但是，可能存在你想自定义这些路由的场景。例如，你可能需要为一个未由 Nuxt 生成的动态页面添加路由，删除已有路由，或修改某个路由的配置。针对这些自定义，Nuxt 提供了 `extendPages` 功能，允许你扩展和更改页面配置。

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/extend-and-alter-nuxt-pages?friend=nuxt" target="_blank"}
观看 Vue School 关于 extendPages 的视频教程。
::

### 用法

```ts twoslash
import { createResolver, defineNuxtModule, extendPages } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    extendPages((pages) => {
      pages.unshift({
        name: 'prismic-preview',
        path: '/preview',
        file: resolve('runtime/preview.vue'),
      })
    })
  },
})
```

### 类型

```ts
function extendPages (callback: (pages: NuxtPage[]) => void): void
```

### 参数

**callback**：一个函数，将接收页面配置数组。你可以通过添加、删除或修改其元素来改变页面配置。注意：应该直接修改传入的 pages 数组，复制数组上的修改不会反映到配置中。

| 属性         | 类型                               | 是否必需    | 描述                              |
| ---------- | -------------------------------- | ------- | ------------------------------- |
| `name`     | `string`                         | `false` | 路由名称。用于编程式导航和识别路由。              |
| `path`     | `string`                         | `false` | 路由的 URL 路径。若未设置，Nuxt 会根据文件位置推断。 |
| `file`     | `string`                         | `false` | 作为路由组件使用的 Vue 文件路径。             |
| `meta`     | `Record<string, any>`{lang="ts"} | `false` | 自定义路由元数据。可用于布局、中间件或导航守卫。        |
| `alias`    | `string[] \| string`{lang="ts"}  | `false` | 路由的一个或多个别名路径。支持多个网址。            |
| `redirect` | `RouteLocationRaw`{lang="ts"}    | `false` | 路由重定向规则。支持命名路由、对象或字符串路径。        |
| `children` | `NuxtPage[]`{lang="ts"}          | `false` | 该路由下嵌套的子路由，用于布局或视图嵌套。           |

## `extendRouteRules`

Nuxt 使用 [Nitro](https://nitro.zhcndoc.com/) 作为服务器引擎。借助 Nitro，你可以直接在配置中加入高级逻辑，例如重定向、代理、缓存及为路由附加头部信息等。此配置通过将路由模式与特定的路由设置关联实现。

::tip
你可以在 [Nitro 文档](https://nitro.zhcndoc.com/guide/routing#route-rules) 了解更多关于 Nitro 路由规则的信息。
::

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt" target="_blank"}
观看 Vue School 课程，了解如何添加路由规则和路由中间件。
::

### 用法

```ts twoslash
import { createResolver, defineNuxtModule, extendPages, extendRouteRules } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    extendPages((pages) => {
      pages.unshift({
        name: 'preview-new',
        path: '/preview-new',
        file: resolve('runtime/preview.vue'),
      })
    })

    extendRouteRules('/preview', {
      redirect: {
        to: '/preview-new',
        statusCode: 302,
      },
    })

    extendRouteRules('/preview-new', {
      cache: {
        maxAge: 60 * 60 * 24 * 7,
      },
    })
  },
})
```

### 类型

```ts
function extendRouteRules (route: string, rule: NitroRouteConfig, options?: ExtendRouteRulesOptions): void
```

### 参数

**route**：用于匹配的路由模式。  
**rule**：应用于匹配路由的路由规则配置。

::tip
关于路由规则配置的更多详情，请参阅[混合渲染 > 路由规则](https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/rendering#route-rules)。
::

**options**：传递给路由配置的对象。如果 `override` 设置为 `true`，将覆盖已有路由配置。

| 名称         | 类型        | 默认值     | 描述                     |
| ---------- | --------- | ------- | ---------------------- |
| `override` | `boolean` | `false` | 是否覆盖现有路由规则配置，默认是 false |

## `addRouteMiddleware`

注册路由中间件，使其可用于所有路由或特定路由。

路由中间件也可以通过插件中的 [`addRouteMiddleware`](https://nuxt.zhcndoc.com/docs/3.x/api/utils/add-route-middleware) 组合式函数来定义。

::tip
在[路由中间件文档](https://nuxt.zhcndoc.com/docs/3.x/getting-started/routing#route-middleware)中了解更多关于路由中间件的信息。
::

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt" target="_blank"}
观看 Vue School 课程，了解如何添加路由规则和路由中间件。
::

### 用法

::code-group
```ts twoslash [module.ts]
import { addRouteMiddleware, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addRouteMiddleware({
      name: 'auth',
      path: resolve('runtime/auth'),
      global: true,
    }, { prepend: true })
  },
})
```

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

### 类型

```ts
function addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], options?: AddRouteMiddlewareOptions): void
```

### 参数

**input**：中间件对象或中间件数组，包含以下属性：

| 属性       | 类型        | 是否必需    | 描述                   |
| -------- | --------- | ------- | -------------------- |
| `name`   | `string`  | `true`  | 中间件名称。               |
| `path`   | `string`  | `true`  | 中间件文件路径。             |
| `global` | `boolean` | `false` | 如果为 `true`，则应用于所有路由。 |

**options**：带有以下属性的对象：

| 属性         | 类型        | 默认值     | 描述                         |
| ---------- | --------- | ------- | -------------------------- |
| `override` | `boolean` | `false` | 如果为 `true`，会替换同名的中间件。      |
| `prepend`  | `boolean` | `false` | 如果为 `true`，将中间件添加到现有中间件之前。 |

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/pages.ts)


## Sitemap

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