Codifica/Decodifica Base64 in JavaScript: btoa(), atob() e Unicode

Codifica e decodifica Base64 in JavaScript

JavaScript fornisce diversi modi integrati per codificare e decodificare stringhe Base64. Che tu stia creando un'applicazione browser o un server Node.js, capire come lavorare con Base64 è essenziale per gestire dati binari in formati basati su testo come JSON, HTML e URL.

Usare btoa() e atob() nel Browser

Le due funzioni principali per Base64 nel JavaScript del browser sono btoa() e atob(). Questi nomi di funzione seguono una convenzione di denominazione più vecchia — btoa sta per "binary to ASCII" (da binario ad ASCII) e atob sta per "ASCII to binary" (da ASCII a binario). Sono supportate in tutti i browser principali da decenni.

Codifica con btoa()

const originalString = 'Hello, world!';
const encoded = btoa(originalString);
console.log(encoded);
// Output: SGVsbG8sIHdvcmxkIQ==

Decodifica con atob()

const base64String = 'SGVsbG8sIHdvcmxkIQ==';
const decoded = atob(base64String);
console.log(decoded);
// Output: Hello, world!

Entrambe le funzioni funzionano con stringhe che contengono solo caratteri Latin-1 (ogni carattere rappresentato da un singolo byte). Questa è una limitazione importante che affronteremo subito.

Gestione di Unicode e Caratteri Non-ASCII

Una trappola comune: btoa() genera un errore quando riceve stringhe contenenti caratteri al di fuori dell'intervallo Latin-1, come emoji, caratteri cinesi o lettere accentate.

btoa('Hello 你好');
// Error: The string to be encoded contains characters outside of the Latin-1 range.

Per codificare stringhe Unicode, devi prima convertire la stringa in byte e poi codificare quei byte. L'approccio moderno usa le API TextEncoder e TextDecoder:

function unicodeToBase64(str) {
  const bytes = new TextEncoder().encode(str);
  const binaryString = String.fromCharCode(...bytes);
  return btoa(binaryString);
}

function base64ToUnicode(base64) {
  const binaryString = atob(base64);
  const bytes = Uint8Array.from(binaryString, (c) => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

// Usage
const encoded = unicodeToBase64('Hello 你好 🚀');
console.log(encoded);
// Output: SGVsbG8g5L2g5aW9IPCfj4A=

const decoded = base64ToUnicode(encoded);
console.log(decoded);
// Output: Hello 你好 🚀

Una tecnica più vecchia usa encodeURIComponent e decodeURIComponent, ma l'approccio TextEncoder/TextDecoder è più robusto ed è la soluzione moderna consigliata.

Codifica di Dati Binari (ArrayBuffer)

Quando lavori con file, immagini o dati binari grezzi provenienti da API come fetch o FileReader, in genere hai un ArrayBuffer o un Uint8Array. Ecco come convertirlo in Base64:

function arrayBufferToBase64(buffer) {
  const bytes = new Uint8Array(buffer);
  let binaryString = '';
  for (let i = 0; i < bytes.length; i++) {
    binaryString += String.fromCharCode(bytes[i]);
  }
  return btoa(binaryString);
}

function base64ToArrayBuffer(base64) {
  const binaryString = atob(base64);
  const bytes = new Uint8Array(binaryString.length);
  for (let i = 0; i < binaryString.length; i++) {
    bytes[i] = binaryString.charCodeAt(i);
  }
  return bytes.buffer;
}

Convertire un File in Base64 nel Browser

Ecco un esempio completo che usa FileReader per convertire un file selezionato dall'utente in un data URL Base64:

function fileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = () => reject(new Error('Failed to read file'));
    reader.readAsDataURL(file);
  });
}

// Usage with a file input
document.querySelector('input[type="file"]').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  try {
    const dataUrl = await fileToBase64(file);
    console.log(dataUrl); // data:image/png;base64,iVBORw0KGgo...
  } catch (err) {
    console.error('Conversion failed:', err);
  }
});

Usare Base64 in Node.js

Node.js fornisce la classe Buffer per le operazioni Base64, che è più flessibile di btoa/atob del browser. La classe Buffer gestisce automaticamente codifica e decodifica, incluso Unicode, e supporta più formati di codifica.

Codifica e Decodifica di Base

// Encode a string to Base64
const encoded = Buffer.from('Hello, world!').toString('base64');
console.log(encoded);
// Output: SGVsbG8sIHdvcmxkIQ==

// Decode a Base64 string back to text
const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
console.log(decoded);
// Output: Hello, world!

Supporto Unicode in Node.js

A differenza di btoa() nel browser, il Buffer di Node.js gestisce Unicode senza problemi:

const encoded = Buffer.from('Hello 你好 🚀').toString('base64');
console.log(encoded);
// Output: SGVsbG8g5L2g5aW9IPCfj4A=

const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
console.log(decoded);
// Output: Hello 你好 🚀

Leggere un File e Codificarlo in Base64

const fs = require('fs');

// Read a file and encode it to Base64
const buffer = fs.readFileSync('image.png');
const base64 = buffer.toString('base64');
const dataUrl = `data:image/png;base64,${base64}`;

Codifica Base64url in Node.js

Node.js 15.7.0+ supporta la codifica Base64url nativa, che sostituisce + con - e / con _ e omette il padding:

const encoded = Buffer.from('Hello, world!').toString('base64url');
console.log(encoded);
// Output: SGVsbG8sIHdvcmxkIQ (no padding)

const decoded = Buffer.from(encoded, 'base64url').toString('utf-8');
console.log(decoded);
// Output: Hello, world!

Considerazioni sulle Prestazioni

Per dati di grandi dimensioni, operazioni Base64 ripetute possono essere lente. Ecco alcuni consigli:

• Usa TextEncoder/TextDecoder invece delle conversioni manuali per stringhe Unicode
• In Node.js, Buffer.from() è altamente ottimizzato — preferiscilo alle implementazioni manuali
• Evita di convertire file di grandi dimensioni in Base64 a meno che non sia necessario (valuta lo streaming)
• Per set di dati grandi, considera l'uso di Blob e FileReader nel browser per evitare di bloccare il thread principale

Prova la Codifica Base64 Online

Sperimenta con codifica e decodifica direttamente nel tuo browser usando il nostro codificatore e decodificatore Base64 gratuito online. Nessuna programmazione richiesta — incolla semplicemente del testo o carica un file e ottieni il risultato Base64 all'istante.