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

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

## `extendPages`

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

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

### 用法

```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`     | `NuxtPageMeta`{lang="ts"}       | `false` | 路由的自定义元数据。可用于布局、中间件或导航守卫。       |
| `alias`    | `string[] \| string`{lang="ts"} | `false` | 路由的一个或多个别名路径。适用于支持多个 URL。       |
| `redirect` | `RouteLocationRaw`{lang="ts"}   | `false` | 路由的重定向规则。支持命名路由、对象或字符串路径。       |
| `children` | `NuxtPage[]`{lang="ts"}         | `false` | 此路由下用于布局或视图嵌套的嵌套子路由。            |

### 为自定义页面元数据添加类型

使用 `extendPages` 或 `pages:extend` hook 时，你可以扩展 `NuxtPageMeta` 接口，为页面添加类型安全的自定义元数据：

```ts [index.d.ts]
declare module '@nuxt/schema' {
  interface NuxtPageMeta {
    requiresAuth?: boolean
  }
}

export {}
```

```ts [modules/auth.ts]
import { defineNuxtModule, extendPages } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    extendPages((pages) => {
      for (const page of pages) {
        // requiresAuth is now typed as boolean | undefined
        if (page.meta?.requiresAuth) {
          // ...
        }
      }
    })
  },
})
```

## `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/4.x/guide/concepts/rendering#route-rules)。
::

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

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

## `addRouteMiddleware`

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

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

::tip
在[路由中间件文档](https://nuxt.zhcndoc.com/docs/4.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() is an example method verifying if a user is authenticated
  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.