개요

Intl.DateTimeFormat은 JavaScript 국제화 API의 일부로, 추가 라이브러리 없이 날짜와 시간을 지역화된 형식으로 포맷하는 기능 제공 브라우저와 Node.js에서 동작하며, 호스트의 기본 타임존 정보를 IANA 식별자 형태로 노출 가능 서버가 어떤 타임존으로 실행 중인지 확인할 때 resolvedOptions().timeZone 사용

핵심 개념과 정의

국제화 API: 로케일과 캘린더, 숫자 체계, 타임존 등을 기준으로 표기 형식을 결정하는 표준 인터페이스 IANA 타임존 식별자: Asia/Seoul, UTC, America/New_York 같은 표준 명칭 호스트 기본 타임존: 런타임이 인식한 시스템 타임존으로, resolvedOptions().timeZone에서 확인 오프셋과 타임존의 차이: 오프셋은 시점별 UTC와의 분 단위 차이, 타임존은 DST 등 규칙을 포함하는 영역 개념

사용법과 최소 예시

  • 날짜 포맷팅 한 줄 예시 new Intl.DateTimeFormat('ko-KR').format(new Date())

  • 현재 시스템 타임존 확인

const systemTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone
  • 특정 타임존 기준으로 포맷
new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York' }).format(new Date())

서버 타임존 확인에 적용

다음 한 줄로 서버 런타임의 타임존을 식별

const systemTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone

운영 로직 예시 맥락

  • systemTimeZone이 Asia/Seoul이면 추가 보정 없음
  • systemTimeZone이 UTC 또는 그 외 지역이면 KST 기준으로 보여줘야 하는 출력에 변환 필요 권장 방식은 타임존 기반 포맷 옵션 사용이며, 수동으로 +9시간 추가 같은 고정 오프셋 처리 지양 DST가 있는 지역이나 정책 변경 시 고정 오프셋은 쉽게 깨짐

대안과 비교

  • Date.getTimezoneOffset 사용
const offsetMinutes = new Date().getTimezoneOffset()

값은 UTC에서 로컬까지의 분 단위 차이이며, 로컬이 UTC보다 앞서면 음수 예: 한국은 대개 -540으로, 로컬이 UTC보다 9시간 앞섬을 의미 오프셋은 타임존 규칙을 반영하지 못해 변환 로직엔 부적합

  • 환경변수 TZ 확인
process.env.TZ // 예: 'Asia/Seoul' 또는 undefined

배포 환경 설정에 의존하며 항상 설정된다는 보장 없음

  • 하드코딩 플래그 의도는 명확하나 환경 종속성과 유지보수 비용 증가로 비권장

주의사항과 베스트 프랙티스

  • 런타임 의존성 컨테이너나 최소화된 OS 이미지에서 tzdata가 없으면 시스템 타임존이 UTC로만 인식될 수 있음 런타임 빌드 옵션에 따라 ICU 데이터 범위가 달라지고, 일부 환경에선 제한된 로케일이나 타임존만 지원 가능

  • 변환은 오프셋이 아닌 타임존으로 수행 표시나 계산이 KST 기준이면 Intl.DateTimeFormat에 timeZone: ‘Asia/Seoul’을 지정해 포맷 서버 내부 로직은 UTC 저장, 입출력에서만 타임존 변환하는 패턴 권장

  • 검증 배포 환경마다 systemTimeZone 값이 기대와 일치하는지 실행 시 로그로 1회 출력 후 모니터링 권장 테스트에서 Asia/Seoul, UTC, DST 있는 타임존을 최소 1개씩 포함해 포맷 결과 스냅샷 검증 권장

마무리

서버 타임존 확인은 Intl.DateTimeFormat().resolvedOptions().timeZone로 단순하고 표준적으로 해결 가능 표시는 타임존 옵션으로 처리하고, 수동 오프셋 보정은 피하는 것이 안전 환경별 타임존 데이터 유무와 런타임 지원 범위를 점검해 일관된 결과를 확보하는 흐름 추천

참고자료