---
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" target="_blank" to="https://vueschool.io/lessons/extend-and-alter-nuxt-pages?friend=nuxt">

观看关于 extendPages 的 Vue School 视频。

</tip>

### 用法

```tstwoslash
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` 数组，因为对复制数组所做的更改不会反映在配置中。

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      路由的名称。适用于编程式导航和标识路由。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      路由 URL 路径。如果未设置，Nuxt 将根据文件位置推断。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        file
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      应作为路由组件使用的 Vue 文件路径。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meta
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          NuxtPageMeta
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      路由的自定义元数据。可用于布局、中间件或导航守卫。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        alias
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          string[]
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          string
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      路由的一个或多个别名路径。适用于支持多个 URL。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        redirect
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          RouteLocationRaw
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      路由的重定向规则。支持命名路由、对象或字符串路径。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        children
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          NuxtPage[]
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      此路由下用于布局或视图嵌套的嵌套子路由。
    </td>
  </tr>
</tbody>
</table>

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

使用 `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>

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt">

观看 Vue School 关于添加路由规则和路由中间件的视频。

</tip>

### 用法

```tstwoslash
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**：要匹配的路由模式。<br />

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

<tip>

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

</tip>

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

<table>
<thead>
  <tr>
    <th>
      名称
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        override
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      覆盖路由规则配置，默认值为 false
    </td>
  </tr>
</tbody>
</table>

## `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>

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt">

观看 Vue School 关于添加路由规则和路由中间件的视频。

</tip>

### 用法

<code-group>

```ts [module.ts]twoslash
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 [runtime/auth.ts]twoslash
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')
  }
})
```

</code-group>

### 类型

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

### 参数

**input**：一个中间件对象或中间件对象数组，具有以下属性：

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      中间件的名称。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      中间件文件的路径。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        global
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      如果设置为 <code>
        true
      </code>
      
      ，则将中间件应用于所有路由。
    </td>
  </tr>
</tbody>
</table>

**options**：一个具有以下属性的对象：

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        override
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      如果为 <code>
        true
      </code>
      
      ，则替换具有相同名称的中间件。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      如果为 <code>
        true
      </code>
      
      ，将在现有中间件之前预先添加该中间件。
    </td>
  </tr>
</tbody>
</table>

---

- [源码](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.