NextJS 15生产构建报错：{ uuid: string; } 类型缺失Promise的核心属性

看起来你遇到的是Next.js 15生产构建时的TypeScript类型兼容性问题——开发环境正常但生产构建失败，核心问题是TypeScript错误地认为页面组件的params属性应该是Promise类型，而非预期的静态对象类型。下面是对问题的分析和分步解决方案：

可能的原因 #

1. TypeScript版本与Next.js 15不兼容（Next.js 15建议使用TypeScript 5.3+版本）
2. 项目tsconfig.json配置导致类型推断异常
3. 全局类型定义中存在冲突的PageProps类型
4. 构建缓存残留引发的类型检查逻辑异常

分步解决方案 #

1. 升级TypeScript与Next.js版本 #

Next.js 15对TypeScript版本有明确要求，先升级到兼容版本：

npm install typescript@5.3+ next@latest --save-dev

2. 显式明确页面组件的类型定义 #

虽然你的类型定义逻辑上正确，但可以通过更清晰的声明避免TypeScript的推断错误：

// 显式定义页面Props类型
type CheckoutPageProps = {
  params: {
    uuid: string;
  };
};

export default async function CheckoutPage({ params }: CheckoutPageProps) {
  const checkoutData = await getCheckoutData(params.uuid);
  if (checkoutData.status === true) {
    redirect('/');
  }
  
  return (
    // 原有JSX内容保持不变
    <div className="mx-auto max-w-7xl px-6 lg:px-8 py-12 flex items-start space-y-6 flex-col w-full sm:w-[400px]">
        <h3 className="text-xl tracking-tight text-pretty line-clamp-2 text-ellipsis overflow-hidden">
          {checkoutData.title}
        </h3>
      <Progress value={50} />
      <CheckoutForm checkoutData={checkoutData} />
      <p className="text-sm text-muted-foreground">Clears instantly 24/7</p>
    </div>
  );
}

3. 修正tsconfig.json配置 #

确保你的tsconfig.json符合Next.js App Router的推荐配置，重点检查以下选项：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "preserve",
    "strict": true,
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

4. 清除缓存后重新构建 #

开发环境的缓存可能导致类型检查不严格，生产构建时缓存残留会引发问题，执行以下命令清理后重试：

rm -rf .next node_modules package-lock.json
npm install
npm run build

5. 检查全局类型定义冲突 #

检查项目中是否存在自定义的PageProps类型（比如在types/global.d.ts或其他类型文件中），如果有，确保其params属性不是Promise类型：

// 如果存在以下错误定义，请删除或修改
type PageProps = {
  params: Promise<any>;
};

如果以上方法都无效，可以临时将tsconfig.json中的"strict": false关闭，验证是否是严格模式导致的类型推断问题（仅用于排查，生产环境建议保持严格模式）。

备注：内容来源于stack exchange，提问作者Marc Kch