Next.js 13.4构建报错：'ResolvingMetadata | undefined'不符合约束

我在Next.js 13.4应用中使用以下代码动态生成metadata，开发环境运行正常，但构建时遇到类型错误：

export async function generateMetadata(
    { params, searchParams }: Props,
) {
    try {
        // read route params
        const id = params.itemId;

        // fetch data
        const product = await fetch(`${baseUrl}/catelog/item/find/${id}`, {cache: 'no-store'}).then((res) => res.json());

        return {
            title: `Example | ${product.product_name}`,
            description: product.product_description ?? `best selling items at Example store`,
            openGraph: {
                images: [product.product_image],
                title: `Example | ${product.product_name}`,
                description: product.product_description ?? `best selling items at Example store`,
                type: "website"
            },
        };
    } catch (e) {
        return {
            title: `Example | Not found`,
            description: `Product not found`,
        }
    }
}

错误信息：

Type error: Type 'ResolvingMetadata | undefined' does not satisfy the constraint 'ResolvingMetadata'.
  Type 'undefined' is not assignable to type 'Promise<ResolvedMetadata>'.

问题根因 #

这个错误的核心是TypeScript对generateMetadata函数的参数/返回类型推断出现问题。在Next.js 13.4的App Router中，generateMetadata有严格的类型约束，当未显式指定参数、返回值类型时，严格模式下的TypeScript可能错误推断出包含undefined的类型，触发构建时的类型检查失败。

常见触发场景：

• 未显式定义params、searchParams的结构类型
• 未指定函数返回类型为Next.js要求的Metadata类型
• 自定义的Props类型与Next.js期望的参数类型不匹配

修复方案 #

通过显式导入Next.js官方元数据类型，并明确函数的参数和返回类型，即可解决该错误。修改后的代码如下：

import type { Metadata, ResolvingMetadata } from 'next';

// 根据你的路由结构，显式定义参数类型
type GenerateMetadataProps = {
  params: { itemId: string };
  searchParams: Record<string, string | string[]>;
};

export async function generateMetadata(
  { params, searchParams }: GenerateMetadataProps,
  // 若不需要父级metadata，可标记为可选
  parent?: ResolvingMetadata
): Promise<Metadata> {
  try {
    const id = params.itemId;
    // 确保baseUrl已正确定义，建议从环境变量读取
    const baseUrl = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000';
    
    const product = await fetch(`${baseUrl}/catelog/item/find/${id}`, { cache: 'no-store' }).then(res => res.json());

    return {
      title: `Example | ${product.product_name}`,
      description: product.product_description ?? 'best selling items at Example store',
      openGraph: {
        images: [product.product_image],
        title: `Example | ${product.product_name}`,
        description: product.product_description ?? 'best selling items at Example store',
        type: 'website'
      },
    };
  } catch (e) {
    return {
      title: `Example | Not found`,
      description: 'Product not found',
    };
  }
}

关键修复点：

• 导入Next.js官方的Metadata和ResolvingMetadata类型，确保类型约束匹配
• 显式定义GenerateMetadataProps类型，明确参数结构，避免TypeScript错误推断
• 指定函数返回类型为Promise<Metadata>，符合Next.js的要求
• 给baseUrl设置默认值，避免未定义的运行时风险

内容的提问来源于stack exchange，提问作者Githendra McShane