next.config.js: deploymentId | Next.js

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId

deploymentId

최종 업데이트 2026년 2월 20일

deploymentId 옵션을 사용하면 배포에 대한 식별자를 설정할 수 있습니다. 이 식별자는 롤링 배포 동안 버전 차이 보호와 캐시 무효화에 사용됩니다.

next.config.js

    module.exports = {
      deploymentId: 'my-deployment-id',
    }

NEXT_DEPLOYMENT_ID 환경 변수를 사용해 배포 ID를 설정할 수도 있습니다:

    NEXT_DEPLOYMENT_ID=my-deployment-id next build

알아두면 좋아요: 둘 다 설정된 경우 next.config.js의 deploymentId 값이 NEXT_DEPLOYMENT_ID 환경 변수보다 우선합니다.

작동 방식

deploymentId를 구성하면 Next.js는 다음을 수행합니다:

정적 자산 URL(JavaScript, CSS, 이미지)에 ?dpl=<deploymentId>를 추가합니다.
클라이언트 측 내비게이션 요청에 x-deployment-id 헤더를 추가합니다.
내비게이션 응답에 x-nextjs-deployment-id 헤더를 추가합니다.
<html> 요소에 data-dpl-id 속성을 주입합니다.

클라이언트가 응답 헤더를 통해 자신의 배포 ID와 서버의 배포 ID가 일치하지 않음을 감지하면, 클라이언트 측 내비게이션 대신 하드 내비게이션(전체 페이지 새로고침)을 트리거합니다. 이렇게 하면 사용자가 항상 동일한 배포 버전의 자산과 Server Functions를 받도록 보장됩니다.

알아두면 좋아요: Next.js는 수신 요청에서 ?dpl= 쿼리 매개변수를 읽지 않습니다. 이 쿼리 매개변수는 라우팅이 아니라 캐시 무효화(브라우저와 CDN이 최신 자산을 가져오도록 보장)에 사용됩니다. 버전에 민감한 라우팅이 필요하면 배포 기반 라우팅 구현에 대해 호스팅 제공자나 CDN 문서를 참조하세요.

사용 사례

롤링 배포

롤링 배포 중에는 일부 서버 인스턴스가 새 버전을 실행하는 반면 다른 인스턴스는 기존 버전을 실행할 수 있습니다. 배포 ID가 없으면 사용자가 이전 자산과 새로운 자산을 혼합해 받아 오류가 발생할 수 있습니다.

배포마다 일관된 deploymentId를 설정하면 다음을 보장할 수 있습니다:

클라이언트가 항상 동일한 배포 버전의 자산을 요청합니다.
불일치가 발생하면 전체 새로고침을 트리거하여 올바른 자산을 가져옵니다.
Server Functions가 배포 경계를 넘어 제대로 작동합니다.

다중 서버 환경

로드 밸런서 뒤에서 여러 인스턴스로 Next.js 애플리케이션을 실행하는 경우 동일한 배포에 속하는 모든 인스턴스가 동일한 deploymentId를 사용해야 합니다.