Next.js 15.1 이후 params 타입 오류 해결

봄·2025년 4월 16일

🖤 Next.js

목록 보기

5/11

❗ 문제 상황

Next.js 15.2.4에서 npm run build 실행 시 다음과 같은 타입 오류(Type error) 발생:

src/app/book/[id]/page.tsx
Type error: Type '{ params: { id: string | string[]; }; }' does not satisfy the constraint 'PageProps'.
  Types of property 'params' are incompatible.
    Type '{ id: string | string[]; }' is missing the following properties from type 'Promise<any>': then, catch, finally, [Symbol.toStringTag]

📎 문제 원인

Next.js 15.1 버전부터 App Router에서 params와 searchParams가 비동기(Promise 기반) 로 처리되도록 변경되었다.

이로 인해 기존처럼 params: { id: string }와 같이 동기적인 타입으로 선언할 경우, Next.js 내부에서 params를 Promise로 처리하려고 하면서 타입 불일치 에러가 발생한다.

즉, params가 { id: string }일 것이라 가정하고 코드를 작성하면, 실제로는 Promise<{ id: string }>이 들어오므로 타입 충돌이 발생하게 된다.

🧩 문제 요약

빌드 시 발생한 오류는 Next.js 내부적으로 params를 비동기로 처리하는 방식으로 바뀌었음에도, 코드에서는 여전히 동기 타입으로 선언했기 때문에 발생했다.

이는 Next.js 15.1 이후의 중요한 구조 변경 사항 중 하나다.

✅ 해결 방법

params의 타입을 Promise로 감싸 비동기 처리로 변경해야 한다.

아래와 같은 방식으로 코드를 수정하면 됨

params의타입을 Promise<{ id: string }>로 감싸고, 내부에서 await 로 비동기적으로 처리

import ClientComponent from "@/app/components/ClientComponent";

// 변환된 타입 정의
type PageParams = Promise<{ id: string }>;

const Page = async ({ params }: { params: PageParams }) => {
  const { id } = await params; // 비동기로 변환

  return (
    <div>
      Page {id}
      <ClientComponent>
        <></>
      </ClientComponent>
    </div>
  );
};

export default Page;