Next.js 15+ 中 Promise 类型的 params 如何避免异步客户端组件警告？

2026-11-06数据阿明

Next.js 15+ 中，页面的 params 类型是 Promise，带有 'use client' 的组件则不能声明为 async。可以让页面保持为 Server Component，在服务端等待 params，再将所需参数作为普通属性传给同步的客户端组件。这样也能避免在 Client Component 中创建或等待未缓存的 Promise。

将页面和客户端组件拆开

页面文件不添加 'use client'，由它负责处理异步参数：

// app/[refId]/page.tsx
import DynamicRouteClient from './DynamicRouteClient';

type PageProps = {
  params: Promise<{ refId: string }>;
};

export default async function Page({ params }: PageProps) {
  const { refId } = await params;

  return <DynamicRouteClient refId={refId} />;
}

交互界面放在客户端组件中。它接收已解析的字符串，因此不需要声明为异步函数：

// app/[refId]/DynamicRouteClient.tsx
'use client';

type Props = {
  refId: string;
};

export default function DynamicRouteClient({ refId }: Props) {
  // 在这里实现客户端交互
  return <div>{refId}</div>;
}

根据项目的实际目录调整文件名和导入路径。如果页面没有客户端交互，可以移除 'use client'，在 Server Component 中读取参数并完成页面渲染。

为什么原写法会触发警告

原代码在模块顶部声明了 'use client'，组件函数也声明为 async 并执行 await params。Next.js 会因此将它识别为异步 Client Component，而当前客户端组件不支持这种写法。客户端组件或 Hook 内创建并等待 Promise，也可能触发未缓存 Promise 的提示。

在 React 18 下，将组件拆分开并在 Server Component 中等待 params，可以避免依赖 React 19 的 use() 来读取 Promise。如果为了消除 PageProps 类型错误而把页面改成异步客户端组件，应调整组件边界和属性类型，避免在带有 'use client' 的页面中等待 params。