Errori del convertitore epoch: evitare conversioni di timestamp Unix errate

I sette errori che producono una data sbagliata

Un convertitore epoch fa aritmetica semplice, quindi quando l'output è sbagliato la causa non è quasi mai la matematica — è l'input. Un timestamp non porta un'etichetta che dica se è in secondi o millisecondi, in UTC o locale, o quanto è preciso, e ogni conversione errata nasce dall'indovinare male uno di questi punti. L'indizio più rapido è l'anno risultante: una data vicina al 1970 o a migliaia di anni nel futuro è una confusione di unità, e una data corretta ma sfasata di un numero tondo di ore è un errore di fuso. La tabella sottostante è la guida pratica; le sezioni successive spiegano in dettaglio gli errori di unità e di fuso e mostrano come verificare una conversione nel codice.

• Apri il convertitore da epoch a data

Cosa fa un convertitore epoch

Un convertitore epoch trasforma i timestamp numerici in date leggibili e riconverte le date umane in timestamp epoch. Uno buono gestisce secondi Unix, millisecondi Unix, output UTC, output in fuso locale e stringhe ISO 8601, e rende evidente l'unità prima che tu copi un valore in codice, in un database o in una richiesta API. Convertitore epoch, convertitore di tempo Unix, convertitore di timestamp Unix e calcolatore di epoch Unix descrivono lo stesso lavoro: tradurre tra un conteggio di secondi (o millisecondi) dal 1° gennaio 1970 UTC e una data che un umano possa leggere. Il convertitore è raramente il problema — di solito lo è l'input.

Gli errori di unità: secondi, millisecondi, micro, nano

L'errore di conversione di gran lunga più comune è una confusione di unità, e ha una firma: la data finisce nel 1970, o a migliaia di anni. JavaScript è dove morde più spesso, perché sia il costruttore Date sia Date.now() lavorano in millisecondi mentre la maggior parte delle API, dei database e il comando Unix date lavorano in secondi. Passa un valore in secondi a 10 cifre a new Date() senza moltiplicare per 1000 e atterri 53 anni troppo presto. Al contrario — dare millisecondi a 13 cifre a una funzione in secondi — scaglia la data lontano nel futuro. Le sorgenti a precisione maggiore peggiorano le cose: i database emettono spesso microsecondi a 16 cifre e i sistemi di tracing nanosecondi a 19 cifre, ed entrambi sembrano un valore Unix valido finché non si decodificano nel millennio sbagliato.

• 10 cifre → secondi (es. 1700000000); 13 → millisecondi; 16 → microsecondi; 19 → nanosecondi
• JavaScript: new Date(seconds * 1000), oppure new Date(ms) direttamente
• Microsecondi → dividere per 1.000.000 prima di convertire; nanosecondi → per 1.000.000.000
• Verifica di buon senso: il risultato deve essere una data plausibile nel decennio attuale

• MDN — il costruttore Date() (si aspetta millisecondi)
• Millisecondi vs secondi — la guida completa alle unità

Gli errori di fuso orario: UTC vs locale e ora legale

Una volta corretta l'unità, gli errori restanti sono errori di fuso, e anche loro condividono una firma: la data è corretta ma l'orologio è sfasato di un numero intero di ore. Un timestamp Unix è un singolo istante senza fuso proprio; l'offset viene applicato solo quando l'istante viene formattato. Quindi due convertitori impostati su fusi diversi mostrano orari diversi per lo stesso numero — nessuno sbaglia, mostrano semplicemente viste locali diverse. La trappola è copiare un'ora locale da orologio a muro senza annotare da quale fuso proviene, o convertire un'ora che cade su un cambio di ora legale, dove un'ora locale può verificarsi due volte o mai. Quando un risultato è sfasato di esattamente un'ora, sospetta dell'ora legale prima di sospettare del convertitore.

• Confrontare i valori in UTC; applicare un fuso locale solo nel momento in cui li mostri
• Non salvare mai un'ora locale senza salvare anche il suo fuso IANA o offset UTC
• Intorno a un cambio di ora legale, derivare l'istante dall'UTC, non da un'ora locale ambigua

• Database dei fusi orari IANA (le regole usate da ogni runtime)
• Ora legale e timestamp Unix

Scegli prima la direzione

La maggior parte delle attività con i timestamp va in una di due direzioni: da epoch a data, o da data a epoch. Decidere prima la direzione previene la causa più comune di dati di test errati e payload API rotti — convertire il valore giusto nel verso sbagliato.

• Da epoch a data: incolla 1700000000 e leggi la data UTC o locale
• Da data a epoch: scegli 2026-01-01 00:00:00 UTC e ottieni 1767225600
• Conferma se la destinazione si aspetta secondi o millisecondi prima di copiare il risultato

Cosa verificare prima di copiare un valore convertito

Un convertitore può essere corretto solo quanto l'input è inequivocabile. Prima di copiare un timestamp in un test, un cron, una migrazione o una richiesta API, conferma l'unità, il fuso e la precisione attesa. La verifica di buon senso più rapida è l'anno risultante: una data vicina al 1970 o lontana nel futuro segnala quasi sempre una confusione di unità più che un errore del convertitore.

• Il sistema ricevente si aspetta secondi o millisecondi?
• La data mostrata è in UTC o in ora locale?
• Il timestamp rappresenta un istante o una data di calendario locale?
• La colonna del database memorizza datetime nativo, secondi Unix o millisecondi Unix?
• Il risultato è vicino al 1970 o lontano nel futuro, cosa che di solito segnala una confusione di unità?

Verificare una conversione nel codice

Quando un valore convertito conta — una migrazione, un confine di fatturazione, una pianificazione cron — non fidarti di un solo strumento. Ricava di nuovo lo stesso istante nel tuo runtime e verifica che i due concordino in UTC. Ognuna di queste righe stampa una stringa ISO 8601 inequivocabile con suffisso Z, quindi non c'è alcuna congettura sul fuso locale da confrontare.

• JavaScript: new Date(1700000000 * 1000).toISOString() // '2023-11-14T22:13:20.000Z'
• Python: datetime.fromtimestamp(1700000000, tz=timezone.utc).isoformat()
• Shell (GNU): date -u -d @1700000000 +'%Y-%m-%dT%H:%M:%SZ'
• Se lo strumento e il tuo runtime non concordano, il sospetto è l'unità o il fuso dell'input — non il convertitore

• Python — datetime.fromtimestamp
• Tempo Unix in data — la ricetta di conversione in ogni linguaggio

Esempio pratico: un istante, tre rappresentazioni

Prendi l'istante 2026-01-01 00:00:00 UTC. Come secondi Unix è 1767225600; come millisecondi Unix è 1767225600000; come ISO 8601 è 2026-01-01T00:00:00Z. Tutti e tre descrivono lo stesso momento — cambiano solo formato e unità. L'istante non porta mai un fuso proprio; New York mostrerebbe lo stesso valore come 2025-12-31 19:00:00, perché l'offset viene applicato al momento della visualizzazione, non memorizzato nel numero.

Articoli correlati

• 10 bug comuni dei timestamp Unix (gli stessi problemi nel codice)
• Millisecondi vs secondi — confusione di unità
• Ora legale e timestamp Unix
• Il problema dell'anno 2038
• Tempo Unix in data
• Convertitore da epoch a data (strumento)