JavaScript에서 Unix 타임스탬프 다루기

JavaScript 타임스탬프 치트시트

JavaScript는 밀리초로 동작합니다: Date.now()와 Date 생성자는 둘 다 Unix 에포크 이후의 밀리초를 쓰는 반면, 다른 대부분의 시스템은 초를 씁니다 — 그래서 거의 모든 JavaScript 타임스탬프 작업은 × 1000 또는 ÷ 1000을 기억하는 것으로 귀결됩니다. 아래 표가 빠른 참조이고, 그 뒤의 절들이 각 연산을 설명하며, 심화 가이드가 시간대와 Temporal API를 완전히 다룹니다.

현재 Unix 타임스탬프 얻기

JavaScript는 현재 시각을 숫자 타임스탬프로 얻는 동등한 방법을 여러 가지 제공합니다. 모두 Unix 에포크 이후의 밀리초 수를 반환합니다.

• Date.now() → 가장 빠르고 읽기 좋음 — 1700000000000(밀리초)
• Math.floor(Date.now() / 1000) → 초 단위 Unix 타임스탬프 — 1700000000
• +new Date() → Date.now()와 동일, 단항 플러스 연산자 사용
• new Date().getTime() → 명시적 메서드 호출, Date.now()와 같은 결과

• MDN — Date.now()
• JavaScript Date.now() — 심층 분석(performance.now 포함)

Unix 타임스탬프로 Date 객체 만들기

Date 생성자는 에포크 이후의 밀리초를 받습니다. 초 기반 타임스탬프는 생성자에 넘기기 전에 항상 1000을 곱하세요.

• new Date(1700000000 * 1000) → 초에서(가장 흔한 경우)
• new Date(1700000000000) → 밀리초에서(JavaScript API, Java)
• new Date(Date.now()) → 현재 시각을 Date 객체로
• new Date(0) → Unix 에포크: 1970년 1월 1일 00:00:00 UTC

• MDN — Date() 생성자

날짜 포매팅 — 내장 문자열 메서드

Date 객체에는 내장 문자열 변환 메서드가 여럿 있습니다. 각각 다른 형식을 만듭니다.

• .toISOString() → '2023-11-15T06:13:20.000Z' — ISO 8601, 항상 UTC, 기계가 읽기 좋음
• .toUTCString() → 'Wed, 15 Nov 2023 06:13:20 GMT' — RFC 7231, 사람이 읽기 좋은 UTC
• .toString() → 전체 시간대 이름이 붙은 로컬 시간대 문자열
• .toLocaleString() → 사용자의 로컬 시간대에서 로케일을 인식하는 형식

시간대를 인식하는 포매팅

시간대를 인식하는 포매팅에는 명시적 timeZone을 붙인 Intl.DateTimeFormat을 쓰세요 — DST를 자동 적용하고 라이브러리가 필요 없습니다. 시간대는 그 자체로 깊은 주제입니다; 전용 JavaScript 시간대 가이드가 formatToParts, 사용자 시간대 감지, 어려운 벽시계→UTC 방향을 다룹니다.

• new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York', dateStyle: 'full', timeStyle: 'long' }).format(date)
• date.toLocaleString('en-GB', { timeZone: 'Europe/London', hour12: false })

• JavaScript에서 시간대 정확한 날짜 포매팅(전체 가이드)
• MDN — Intl.DateTimeFormat

날짜 문자열을 Unix 타임스탬프로 되돌리기

반대 방향 — 날짜 문자열에서 Unix 타임스탬프로 — 에는 Date.parse()를 쓰거나 문자열을 Date 생성자에 넘기세요.

• new Date('2023-11-15T06:13:20Z').getTime() / 1000 → ISO 8601 UTC에서 Unix 초
• new Date('2023-11-15T01:13:20-05:00').getTime() → 오프셋 포함 ISO에서 Unix 밀리초
• Date.parse('2023-11-15T06:13:20Z') → new Date(...).getTime()과 동일
• 예측 가능한 파싱을 위해 항상 명시적 시간대가 있는 ISO 8601 형식을 사용하라

흔한 함정

JavaScript 개발자가 날짜와 타임스탬프에서 가장 자주 저지르는 실수들입니다:

• new Date(1700000000) — × 1000이 빠지면 2023년이 아니라 약 1970년으로 변환됨
• getMonth()는 0–11을 반환하고 1–12가 아님 — 표시할 때 항상 1을 더하라
• new Date('2024-01-01')은 UTC 자정, new Date('2024/01/01')은 로컬 자정
• new Date(2024, 0, 1) = 1월 1일(생성자에서도 월은 0부터 인덱싱)
• '내일'을 얻으려고 86400000ms를 더하면 DST 경계에서 실패할 수 있음 — 대신 setDate(d.getDate() + 1)을 쓰라

• 흔한 Unix 타임스탬프 버그 10가지와 고치는 법

Temporal API — Date의 현대적 대체

TC39의 Temporal API는 Stage 4에 도달했고 현대 브라우저와 Node.js에 탑재됩니다. Date의 핵심 결함을 고칩니다 — 불변이고, 나노초 정밀도이며, 시간대를 인식합니다 — 그리고 Temporal.Instant이 그 Unix 타임스탬프 타입입니다. 탑재된 API는 에포크를 밀리초나 나노초로 변환합니다(오래된 fromEpochSeconds는 제거됨), 그러니 Unix 초는 1000을 곱하세요. 전체 API는 Temporal 전체 가이드를 보세요.

• Temporal.Now.instant() — 나노초 정밀도의 현재 순간
• Temporal.Instant.fromEpochMilliseconds(Date.now()) — JS 밀리초 타임스탬프에서
• Temporal.Instant.fromEpochMilliseconds(1700000000 * 1000) — Unix 초에서(× 1000)
• Temporal.ZonedDateTime — 순간 + IANA 시간대, Date가 그랬어야 할 타입
• Firefox 139+, Chrome 144+, Node.js 26+에 탑재; Safari는 Technology Preview; 나머지는 폴리필

• JavaScript Temporal API — 전체 가이드

더 나아가기

• JavaScript Date.now() 심층 분석
• JavaScript에서 시간대 정확한 날짜 포매팅
• JavaScript Temporal API
• Unix 타임스탬프 형식(초, ms, ISO 8601)
• JavaScript 타임스탬프 스니펫