TIL

Next.js 15에서 HTTP 요청 헤더 쉽게 작성하기 (headers)

Next.js 15에서 HTTP 요청 헤더 쉽게 작성하기 (headers)
TILPosted On Apr 22, 20256 min read

headers 함수 알아보기

headers 함수는 Server Component 내에서 HTTP 요청 헤더를 비동기로 읽을 수 있게 도와주는 유틸리티입니다. 간단히 말해, 클라이언트가 서버에 보낸 요청의 헤더 정보를 서버 컴포넌트 안에서 쉽게 확인할 수 있다는 거죠.

아래 예제를 보고 한번 살펴볼게요!

import { headers } from 'next/headers'

export default async function Page() {
  const headersList = await headers()
  const userAgent = headersList.get('user-agent')

  return (
    <div>
      <p>당신의 User-Agent: {userAgent}</p>
    </div>
  )
}
  • 여기서 headers()를 호출하면 요청에 포함된 모든 헤더 정보를 담은 객체를 비동기로 가져옵니다.
  • headersList.get('user-agent')로 특정 헤더(user-agent) 값을 얻을 수 있어요.
  • 이렇게 얻은 헤더 정보로 클라이언트 환경에 따라 다른 내용을 렌더링하거나, API 요청 시 헤더를 조작할 수도 있습니다.

참고로, headers() 함수는 Server Component에서만 사용 가능하기 때문에 클라이언트 컴포넌트에서는 사용할 수 없다는 점 기억하세요!

헤더 정보 활용 팁

  • 사용자 환경 감지: User-Agent 헤더를 통해 브라우저 종류나 버전을 확인할 수 있어, 맞춤형 UI를 제공할 때 유용해요.
  • 보안 검사: 특정 헤더 값을 검사해서 요청이 정상적인지 체크할 수도 있고, 토큰이나 인증 정보를 확인하는 데도 쓰입니다.
  • 로깅 및 분석: 클라이언트 IP, 언어 설정, 쿠키 등 다양한 헤더 정보를 기록해서 서비스 개선에 활용하세요.

필요할 때마다 headers를 활용하면 서버 사이드에서 더 스마트하게 사용자 요청을 다룰 수 있으니 꼭 기억해두세요!

파라미터

headers는 별도의 파라미터를 받지 않습니다.

반환값

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

여기서 Web Headers 객체란, 웹 요청과 응답에 포함되는 헤더 정보를 나타내는 객체예요. 쉽게 말해서, 서버나 클라이언트가 주고받는 부가 정보를 가지고 있는 거죠. 주로 콘텐츠 타입(Content-Type), 인증 정보(Authorization), 캐시 제어(Cache-Control) 등 다양한 정보를 담고 있답니다.

이 객체가 읽기 전용이라서, 값들을 마음대로 바꾸지는 못하지만, 필요한 경우 새로운 헤더를 만들어서 요청에 추가할 수 있어요. 혹시 헤더를 조작하거나 확인하는 작업이 필요하다면, 이 점 참고하면 좋을 것 같아요!

Headers 객체 메서드 정리해봤어요! 웹 개발할 때 Headers 다룰 일 많으니 참고해 보세요.

메서드설명
Headers.entries()Headers 객체에 들어있는 모든 키/값 쌍을 돌면서 이터레이터(iterator)를 반환해요.
Headers.forEach()Headers 내 각 키/값 쌍에 대해 한 번씩 제공한 함수를 실행해요.
Headers.get()특정 이름을 가진 헤더의 모든 값을 문자열(String)로 반환해요.
Headers.has()해당 헤더가 존재하는지 여부를 boolean으로 알려줘요.
Headers.keys()모든 키를 순회할 수 있는 이터레이터를 반환해요.
Headers.values()모든 값을 순회할 수 있는 이터레이터를 반환해요.

알아두면 좋은 점

  • headers 함수는 비동기(async) 함수라 Promise를 반환해요. 그래서 async/await 문법이나 React에서 제공하는 hook들을 사용해야 합니다.

  • Next.js 14버전 이전까진 headers가 동기 함수였는데, Next.js 15버전에서도 아직 동기 방식으로 접근은 가능하지만 점점 사라질 예정이에요. 호환성 때문에 아직 남겨두고 있긴 합니다.

  • headers는 읽기 전용(Read-only)입니다. 그래서 요청 헤더를 새로 설정하거나 삭제하는 건 불가능해요.

  • headers가 동적으로 API 값을 반환하기 때문에, 해당 라우트(페이지)는 자동으로 ‘동적 렌더링’ 모드로 들어갑니다. 정적 생성(Static Generation)이 필요한 상황에서는 주의하세요.

혹시 Headers 객체를 사용할 때 어떻게 데이터를 순회하는지 궁금하다면, 다음처럼 간단한 예제도 있어요!

const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.append('X-Custom-Header', 'Value123');

for (const [key, value] of headers.entries()) {
  console.log(`${key}: ${value}`);
}

headers.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});

이런 식으로 entries()로 반복문 사용하거나 forEach를 바로 쓸 수 있어요.

개발하시면서 Headers 객체를 다룰 일이 많다면, 이런 기본 메서드들을 익혀두면 훨씬 편리합니다. 꼭 기억해두세요!

Authorization 헤더 사용하기

import { headers } from 'next/headers'
 
export default async function Page() {
  const authorization = (await headers()).get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // Authorization 헤더 전달하기
  })
  const user = await res.json()
 
  return <h1>{user.name}</h1>
}

여기서 중요한 점은, Next.js 13부터 headers() 함수가 비동기 함수가 되었다는 거예요. 그래서 await headers()로 호출해야 하고, 그 결과에서 authorization 헤더 값을 가져올 수 있습니다. 그리고 이 값을 fetch 요청의 헤더로 그대로 넘겨줘서, 서버 간 인증 정보를 전달할 수 있죠.

이 방법은 특히 API 라우트나 서버 컴포넌트에서 클라이언트가 보낸 헤더를 그대로 백엔드 API에 넘길 때 유용해요. 예를 들어, JWT 토큰을 포함한 Authorization 헤더를 안전하게 전달할 수 있다는 뜻이죠.

다만, Authorization 헤더에는 민감한 정보가 많이 담기므로, 꼭 신뢰할 수 있는 환경에서만 이렇게 포워딩하고, 노출되지 않도록 주의해야 합니다.

버전 히스토리

VersionChanges
v15.0.0-RCheaders가 이제 비동기 함수가 되었습니다. 관련 코드 변경을 도와주는 codemod가 제공됩니다.
v13.0.0headers 함수가 도입되었습니다.

참고로, 예전 Next.js 버전에서는 headers가 동기 함수였는데, 비동기 함수로 변경되면서 더 유연한 비동기 작업이 가능해졌어요. 업그레이드할 때는 이 점 꼭 체크하세요! 그리고 authorization 외에도 필요한 다른 헤더들도 동일한 방식으로 가져와서 활용할 수 있답니다.