Next.js App Router 中服务器组件的类型定义与最佳实践-js教程-PHP中文网

Next.js App Router 中服务器组件的类型定义与最佳实践

碧海醫心

发布： 2025-11-03 22:16:02

原创

280人浏览过

Next.js App Router 中服务器组件的类型定义与最佳实践

本文旨在指导开发者在 next.js 13+ 的 app router 架构下，如何正确地为服务器组件（包括页面组件和通用组件）进行类型定义。文章将解释 `nextpage` 类型不再适用于 app router 的原因，并提供针对 `page.tsx` 文件中异步服务器组件以及其他通用服务器组件的类型声明方法，强调参数（如 `params` 和 `searchparams`）的类型化以及 typescript 的类型推断能力。

Next.js App Router 中服务器组件的类型定义与最佳实践

随着 Next.js 13 引入 App Router 架构，组件的组织方式和渲染机制发生了显著变化，特别是服务器组件（Server Components）的引入。这使得传统的类型定义方式，如 NextPage，不再适用于新的模式。理解如何在 App Router 中正确地为服务器组件定义类型，对于构建健壮、可维护的应用至关重要。

理解 NextPage 类型的局限性

在 Next.js 的 pages 目录架构中，NextPage 类型通常用于为页面组件提供类型检查，它期望组件是一个返回 ReactElement 的同步函数组件。然而，在 App Router 中，page.tsx 文件默认导出的是服务器组件，它们可以是异步函数，返回一个 Promise<JSX.Element>。这种差异导致 NextPage 类型与 App Router 中的服务器组件不兼容，尝试将其应用于异步服务器组件会导致 TypeScript 错误，例如：

Type '() => Promise<JSX.Element>' is not assignable to type 'NextPage'.
  Type '() => Promise<JSX.Element>' is not assignable to type 'FunctionComponent<{}> & { getInitialProps?(context: NextPageContext): {} | Promise<{}>; }'.
    Type '() => Promise<JSX.Element>' is not assignable to type 'FunctionComponent<{}>'.
      Type 'Promise<Element>' is missing the following properties from type 'ReactElement<any, any>': type, props, keyts(2322)

登录后复制

这个错误明确指出，NextPage 期望一个 FunctionComponent，而异步服务器组件返回的是一个 Promise，这与 FunctionComponent 的返回类型不匹配。因此，在 App Router 中，我们不应再使用 NextPage 来为服务器组件定义类型。

App Router 中页面组件 (page.tsx) 的类型定义

在 App Router 中，page.tsx 文件作为页面的入口，其默认导出的组件会自动接收 Next.js 提供的特定 props，主要包括 params 和 searchParams。这些 props 允许您访问路由参数和 URL 查询参数。

1. 定义页面组件的 Props 接口

首先，我们需要定义一个接口来描述这些传入的 props：

// app/page.tsx 或 app/[slug]/page.tsx
interface PageProps {
  /**
   * 路由参数，例如在 `app/[slug]/page.tsx` 中，`params` 会包含 `{ slug: string }`。
   */
  params: { [key: string]: string | string[] | undefined };
  /**
   * URL 查询参数，例如 `?name=value&id=1` 会在 `searchParams` 中显示为 `{ name: 'value', id: '1' }`。
   */
  searchParams: { [key: string]: string | string[] | undefined };
}

登录后复制

请注意，params 和 searchParams 的结构会根据您的路由定义和实际 URL 查询参数而变化。上述定义提供了一个通用的结构。在实际项目中，您可以根据需要进一步细化 params 的具体类型，例如：

// app/products/[id]/page.tsx
interface ProductPageProps {
  params: { id: string }; // 明确指定 id 参数为字符串
  searchParams: { [key: string]: string | string[] | undefined };
}

登录后复制

2. 为同步页面组件定义类型

如果您的页面组件是同步的，可以直接将 PageProps 应用到组件函数上：

import CoffeesList from '@/components/CoffeesList';
import FiltersDropdown from '@/components/FiltersDropdown';
import SearchCoffee from '@/components/SearchCoffee';

interface PageProps {
  params: { slug?: string }; // 示例：如果路由有可选的 slug
  searchParams: { [key: string]: string | string[] | undefined };
}

export default function Page({ params, searchParams }: PageProps) {
  // 组件逻辑
  return (
    <main className="flex min-h-screen flex-col bg-gradient-to-t from-slate-300 via-slate-200 to-gray-200">
      <SearchCoffee />
      <div className="flex gap-10 w-full">
        <FiltersDropdown />
        {/* <CoffeesList coffees={products} /> */}
      </div>
    </main>
  );
}

登录后复制

3. 为异步页面组件定义类型

App Router 的一个强大特性是允许页面组件直接作为异步函数，在组件内部进行数据获取。在这种情况下，类型定义方式与同步组件相同，只需在函数声明前添加 async 关键字：

import CoffeesList from '@/components/CoffeesList';
import FiltersDropdown from '@/components/FiltersDropdown';
import SearchCoffee from '@/components/SearchCoffee';
import { getData } from '@/lib/api'; // 假设的异步数据获取函数

interface CoffeeInterface {
  id: string;
  name: string;
  // ... 其他咖啡属性
}

interface PageProps {
  params: { slug?: string };
  searchParams: { [key: string]: string | string[] | undefined };
}

export default async function Page({ params, searchParams }: PageProps) {
  const { products }: { products: CoffeeInterface[] } = await getData(
    "/products"
  );

  return (
    <main className="flex min-h-screen flex-col bg-gradient-to-t from-slate-300 via-slate-200 to-gray-200">
      <SearchCoffee />
      <div className="flex gap-10 w-full">
        <FiltersDropdown />
        <CoffeesList coffees={products} />
      </div>
    </main>
  );
}

登录后复制

关于返回类型推断： 在大多数情况下，TypeScript 能够根据 JSX 的返回推断出组件的返回类型（JSX.Element 或 Promise<JSX.Element>）。因此，您通常不需要显式地声明组件函数的返回类型。

App Router 中通用服务器组件的类型定义

除了 page.tsx 文件，您还可以在 App Router 中创建其他可复用的服务器组件。这些组件的行为与普通的 React 函数组件类似，主要关注其接收的 props。

百度文心百中

百度大模型语义搜索体验中心

查看详情

1. 定义组件的 Props 接口

为组件定义一个清晰的 props 接口是最佳实践：

// components/CoffeesList.tsx
interface CoffeesListProps {
  coffees: CoffeeInterface[];
  // ... 其他 props
}

登录后复制

2. 为通用服务器组件定义类型

将定义的 props 接口应用到组件函数上。这些组件可以是同步的，也可以是异步的，具体取决于它们是否需要进行异步操作（如数据获取）。

同步通用服务器组件：

// components/CoffeesList.tsx
import React from 'react';

interface CoffeeInterface {
  id: string;
  name: string;
  // ... 其他咖啡属性
}

interface CoffeesListProps {
  coffees: CoffeeInterface[];
}

export default function CoffeesList({ coffees }: CoffeesListProps) {
  return (
    <div className="coffees-list">
      {coffees.map(coffee => (
        <div key={coffee.id}>{coffee.name}</div>
      ))}
    </div>
  );
}

登录后复制

异步通用服务器组件：

如果您的通用组件也需要进行异步操作，例如在组件内部获取数据（尽管通常建议在页面组件或布局组件中进行顶级数据获取），您可以将其定义为异步函数：

// components/AsyncDataDisplay.tsx
import React from 'react';

interface DataItem {
  id: string;
  value: string;
}

interface AsyncDataDisplayProps {
  fetchUrl: string;
}

export default async function AsyncDataDisplay({ fetchUrl }: AsyncDataDisplayProps) {
  const response = await fetch(fetchUrl);
  const data: DataItem[] = await response.json();

  return (
    <div>
      {data.map(item => (
        <p key={item.id}>{item.value}</p>
      ))}
    </div>
  );
}

登录后复制

同样，对于通用服务器组件，TypeScript 通常也能很好地推断其返回类型，无需显式声明。

总结与注意事项

告别 NextPage: 在 Next.js 13+ 的 App Router 中，请勿使用 NextPage 类型来定义服务器组件。它专为 pages 目录下的客户端页面组件设计。
聚焦 Props 类型: 对于 App Router 中的所有服务器组件，核心的类型定义工作在于为其接收的 props 定义清晰的接口。
页面组件 (page.tsx) 特殊 Props: page.tsx 组件会自动接收 params 和 searchParams。根据路由结构和 URL 查询参数，为这些 props 定义合适的类型。
异步组件支持: App Router 完全支持将服务器组件（包括页面组件和通用组件）定义为 async 函数，以便在组件内部直接进行数据获取。
TypeScript 类型推断: 在大多数情况下，TypeScript 能够自动推断出组件的返回类型（JSX.Element 或 Promise<JSX.Element>），因此通常不需要显式声明返回类型。
结构清晰: 保持 props 接口定义清晰、具体，有助于提高代码的可读性和可维护性。