문서
App Router 사용하기
API 참조
함수
headers

headers

headers 함수를 사용하면 서버 컴포넌트에서 들어오는 HTTP 요청 헤더를 읽을 수 있습니다.

headers()

이 API는 Web Headers API를 확장합니다. 이는 읽기 전용이므로 나가는 요청 헤더를 set / delete할 수 없습니다.

app/page.tsx
import { headers } from "next/headers";
 
export default function Page() {
  const headersList = headers();
  const referer = headersList.get("referer");
 
  return <div>Referer: {referer}</div>;
}
app/page.js
import { headers } from "next/headers";
 
export default function Page() {
  const headersList = headers();
  const referer = headersList.get("referer");
 
  return <div>Referer: {referer}</div>;
}

알아두면 좋은 점:

  • headers()는 반환 값을 미리 알 수 없는 동적 함수 입니다. 레이아웃이나 페이지에서 이를 사용하면 요청 시 동적 렌더링 으로 라우트가 선택됩니다.

API 참조

const headersList = headers();

매개변수

headers는 매개변수를 받지 않습니다.

반환값

headers는 읽기 전용 Web Headers 객체를 반환합니다.

  • Headers.entries(): 이 객체에 포함된 모든 키/값 쌍을 통과할 수 있는 iterator를 반환합니다.
  • Headers.forEach(): 이 Headers 객체의 각 키/값 쌍에 대해 제공된 함수를 한 번씩 실행합니다.
  • Headers.get(): 주어진 이름을 가진 Headers 객체 내의 헤더의 모든 값의 String 시퀀스를 반환합니다.
  • Headers.has(): Headers 객체에 특정 헤더가 포함되어 있는지 여부를 나타내는 불리언을 반환합니다.
  • Headers.keys(): 이 객체에 포함된 키/값 쌍의 모든 키를 통과할 수 있는 iterator를 반환합니다.
  • Headers.values(): 이 객체에 포함된 키/값 쌍의 모든 값을 통과할 수 있는 iterator를 반환합니다.

예시

데이터 페칭과 함께 사용

headers()는 데이터 페칭을 위한 Suspense와 함께 사용할 수 있습니다.

app/page.js
import { Suspense } from "react";
import { headers } from "next/headers";
 
async function User() {
  const authorization = headers().get("authorization");
  const res = await fetch("...", {
    headers: { authorization }, // 인증 헤더 전달
  });
  const user = await res.json();
 
  return <h1>{user.name}</h1>;
}
 
export default function Page() {
  return (
    <Suspense fallback={null}>
      <User />
    </Suspense>
  );
}

IP 주소

headers()를 사용하여 클라이언트의 IP 주소를 얻을 수 있습니다.

app/page.js
import { Suspense } from "react";
import { headers } from "next/headers";
 
function IP() {
  const FALLBACK_IP_ADDRESS = "0.0.0.0";
  const forwardedFor = headers().get("x-forwarded-for");
 
  if (forwardedFor) {
    return forwardedFor.split(",")[0] ?? FALLBACK_IP_ADDRESS;
  }
 
  return headers().get("x-real-ip") ?? FALLBACK_IP_ADDRESS;
}
 
export default function Page() {
  return (
    <Suspense fallback={null}>
      <IP />
    </Suspense>
  );
}

x-forwarded-for 외에도 headers()는 다음을 읽을 수 있습니다:

  • x-real-ip
  • x-forwarded-host
  • x-forwarded-port
  • x-forwarded-proto

버전 기록

버전변경 사항
v13.0.0headers 도입됨.
generateViewportimageResponse