[TIL] 쿠키의 expires옵션과 maxAge 옵션

🍪 expires vs maxAge 쿠키 유효기간 정리

Next.js App Router 환경에서 서버 컴포넌트와 클라이언트 컴포넌트를 각각 쓰다 보니 cookie를 사용할 일이 많다.
그런데 쿠키는 유효기간을 별도로 설정해주지 않으면 유효기간이 해당 세션으로 정해지기 때문에 세션 스토리지를 쓰는 것과 별반 다름 없어진다. 유효기간을 별도로 지정하여 서버와 클라이언트 컴포넌트에서 모두 쓸 수 있게 하려면 쿠키를 쓸 수밖에 없는데, 이때 쿠키의 유효기간을 설정하는 방법은 크게 두 가지가 있다.
바로 expires랑 maxAge. 이 둘은 비슷해 보이지만 완전히 다르게 작동하니까 목적에 따라 제대로 써야 한다.
두 옵션 모두 회사에서 만들고 있는 서비스에도 적용해서 쓰고 있어서 이참에 정리를 좀 해보려고 한다.

---

✅ expires vs maxAge 차이

옵션	의미	타입	특징	쓸 때
expires	절대 시간	Date 객체	특정 날짜/시간에 정확히 만료됨	"언제까지 유지"처럼 날짜가 정해져 있을 때
maxAge	상대 시간 (초 단위)	숫자	지금부터 몇 초 동안 유지됨	"로그인 후 1시간 유지" 같은 상대적인 시간

---

🧪 예시 코드

expires – 특정 날짜에 만료

import { cookies } from 'next/headers'

cookies().set('accessToken', token, {
  expires: new Date('2025-12-31T23:59:59Z'), // UTC 기준
  httpOnly: true,
  secure: true,
  path: '/',
})

maxAge – 지금부터 1일(24시간) 동안 유지

cookies().set('accessToken', token, {
  maxAge: 60 * 60 * 24, // 1일 (초 단위)
  httpOnly: true,
  secure: true,
  path: '/',
})

---

⚠️ expires 쓸 때 주의할 점

1. 무조건 Date 객체로 넘겨야 한다.
   문자열이나 숫자 넘기면 에러가 발생하거나 무시될 수 있다.

2. 브라우저랑 서버 시간 차이 주의
   expires는 절대 시간이기 때문에, 서버 시간이랑 클라이언트 시간이 어긋나서 예상보다 빨리 만료될 수 있다. 특히, access token을 저장할 때 문제가 될 수 있기 때문에 조심해야 한다.
   그래서 보통 서버 시간 기준으로 계산하는 게 안전하다. 서버에서 전달 받은 토큰의 경우, 만료일자를 알아낼 수 있으니까 그렇게 알아낸 서버 만료일자와 동일하게 세팅해주는 게 좋다.

3. 기본적으로 UTC 기준
   만약 한국 시간으로 설정하려면 UTC로 변환해야 한다.
   예) 2025-12-31 23:59:59 (KST) → 2025-12-31T14:59:59Z

4. expires랑 maxAge를 같이 쓰지 말 것
   둘 다 설정하면 브라우저마다 어떤 걸 우선으로 볼지 달라진다.
   충돌을 피하려면 하나만 쓰자.

5. 만료 시점이 과거이면 쿠키가 삭제된다
   쿠키 지울 땐 이렇게 쓰면 된다:

   cookies().set('accessToken', '', { expires: new Date(0) })

---

🧭 언제 무슨 옵션을 써야 할까?

상황	추천 옵션
"올해 말까지 로그인 유지"	expires
"로그인 후 1시간 동안 유지"	maxAge
"회원가입 후 30일 유지"	maxAge or expires 둘 다 가능 (선호에 따라)
"정해진 날짜에 자동 로그아웃"	expires

---

📝 정리

• 정해진 시점에 쿠키가 만료돼야 하면 → expires
• 상대적인 시간(지금부터 몇 분/시간/일) 동안 유지 → maxAge
• 절대 시간 기준이라면 Date 객체를 써야 하고, 시간대 주의!
• 두 옵션 중에서 하나만 설정하고, 보안 옵션(httpOnly, secure, sameSite)도 함께 설정하는 게 좋다.