Trabalhar com timestamps Unix em JavaScript

Obter o timestamp Unix atual

O JavaScript oferece várias formas equivalentes de obter a hora atual como timestamp numérico. Todas retornam o número de milissegundos desde o epoch Unix.

• Date.now() → the fastest and most readable — 1700000000000 (milliseconds)
• Math.floor(Date.now() / 1000) → Unix timestamp in seconds — 1700000000
• +new Date() → same as Date.now(), using the unary plus operator
• new Date().getTime() → explicit method call, same result as Date.now()

Criar um objeto Date a partir de um timestamp Unix

O construtor Date aceita milissegundos desde o epoch. Sempre multiplique por 1000 um timestamp em segundos antes de passá-lo ao construtor.

• new Date(1700000000 * 1000) → from seconds (most common case)
• new Date(1700000000000) → from milliseconds (JavaScript APIs, Java)
• new Date(Date.now()) → current time as a Date object
• new Date(0) → the Unix epoch: January 1, 1970 00:00:00 UTC

Formatar datas — métodos de string integrados

O objeto Date tem vários métodos integrados de conversão para string. Cada um produz um formato diferente.

• .toISOString() → '2023-11-15T06:13:20.000Z' — ISO 8601, always UTC, machine-readable
• .toUTCString() → 'Wed, 15 Nov 2023 06:13:20 GMT' — RFC 7231, human-readable UTC
• .toString() → local timezone string with full zone name
• .toLocaleString() → locale-aware format in the user's local timezone

Formatação com fuso via Intl.DateTimeFormat

Para uma formatação de data consistente e com fuso, sem bibliotecas externas, use a API Intl.DateTimeFormat. Ela está disponível em todos os navegadores modernos e no Node.js 13+.

• new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York', dateStyle: 'full', timeStyle: 'long' }).format(date)
• date.toLocaleString('en-GB', { timeZone: 'Europe/London', hour12: false })
• new Intl.DateTimeFormat('zh-CN', { timeZone: 'Asia/Shanghai' }).format(date)
• new Intl.DateTimeFormat('en-CA', { timeZone: tz }).formatToParts(date) → array of {type, value} parts for custom layouts

Converter uma string de data de volta em timestamp Unix

Para ir no sentido inverso — de uma string de data para um timestamp Unix — use Date.parse() ou passe a string ao construtor Date.

• new Date('2023-11-15T06:13:20Z').getTime() / 1000 → Unix seconds from ISO 8601 UTC
• new Date('2023-11-15T01:13:20-05:00').getTime() → Unix milliseconds from ISO with offset
• Date.parse('2023-11-15T06:13:20Z') → same as new Date(...).getTime()
• Always use ISO 8601 format with explicit timezone for predictable parsing

Armadilhas comuns

Estes são os erros mais frequentes dos desenvolvedores JavaScript com datas e timestamps:

• new Date(1700000000) — sem × 1000, converte para o ano ~1970 em vez de 2023
• getMonth() retorna 0–11, não 1–12 — sempre some 1 ao exibir
• new Date('2024-01-01') é meia-noite UTC; new Date('2024/01/01') é meia-noite local
• new Date(2024, 0, 1) = 1 de janeiro (o mês também começa em 0 no construtor)
• Somar 86400000 ms para obter «amanhã» pode falhar nas mudanças de horário de verão — use setDate(d.getDate() + 1)

FAQ sobre timestamps Unix em JavaScript

Como obtenho um timestamp Unix em segundos em JavaScript?

Use Math.floor(Date.now() / 1000). Date.now() retorna milissegundos, então divida por 1000 e arredonde para baixo para obter segundos Unix inteiros.

Por que new Date() com um timestamp Unix mostra 1970?

O construtor Date espera milissegundos. Um timestamp em segundos de 10 dígitos deve ser multiplicado por 1000: new Date(seconds * 1000).

Como formato uma data do JavaScript para um fuso específico?

Use Intl.DateTimeFormat com uma opção timeZone explícita, como new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York' }). Ela aplica o horário de verão automaticamente e não precisa de bibliotecas externas.