Lewati ke konten
FrAIFlow

Solusi

Mengapa Base64 bermasalah dengan teks non-Inggris

Jika btoa() dapat menangani Hello tetapi gagal pada teks Korea atau emoji, langkah yang terlewat biasanya adalah pengodean teks. Base64 merepresentasikan byte. String JavaScript harus diubah menjadi byte dengan aturan yang disepakati terlebih dahulu, dan aplikasi penerima harus membalikkan proses itu.

Satu laporan publik membahas markup SVG yang mengandung karakter non-Latin; laporan lain berhasil mendekode konten GitHub API tetapi simbol merek dagangnya rusak. Keduanya berada di sisi berbeda dari batas yang sama. Panggilan atob() yang berhasil menghasilkan string biner, bukan otomatis teks UTF-8 yang terbaca.

Gunakan proses UTF-8 bolak-balik yang lengkap

Jika Anda memelihara kode pembuat Base64, perbaiki batas konversi teks ke biner, bukan membuang karakter pemicu kesalahan. Fungsi bantu JavaScript peramban ini membuat batas tersebut eksplisit. Fungsinya ditujukan untuk muatan teks yang relatif kecil, bukan unggahan besar.

function encodeUtf8Base64(text) {
  const bytes = new TextEncoder().encode(text);
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary);
}
function decodeUtf8Base64(encoded) {
  const binary = atob(encoded);
  const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
  return new TextDecoder("utf-8", {
    fatal: true, ignoreBOM: true
  }).decode(bytes);
}
const original = "Hello, 한글 ™ 🌍";
const encoded = encodeUtf8Base64(original);
const restored = decodeUtf8Base64(encoded);
console.log(encoded); // SGVsbG8sIO2VnOq4gCDihKIg8J+MjQ==
console.log(restored === original); // true

Letakkan fungsi bantu di dekat kode konversi yang ada, lalu uji dengan contoh sebelum memakai konten sebenarnya. Pemeriksaan kesamaan seharusnya menghasilkan true. Jika false, bandingkan string sebelum pengodean dan setelah pendekodean; jangan menilai keberhasilan hanya karena hasilnya “terlihat seperti Base64”. Sertakan huruf beraksen, emoji, dan string kosong dalam pengujian.

Jika Anda hanya menerima data, tanyakan byte apa yang dikodekan pengirim. Alfabet Base64 tidak memberi tahu apakah pengodeannya UTF-8. Dekode Base64 yang berhasil lalu diikuti kesalahan UTF-8 bisa menunjukkan pengodean teks lain atau berkas bukan teks. Untuk PNG atau PDF, pertahankan byte hasil dekode sebagai biner, jangan menjalankan dekoder teks atasnya.

Pada alat untuk pengguna, tangani kesalahan masukan yang tidak valid dan biarkan masukan asli tersedia untuk diedit. Jangan mengganti kegagalan dekode dengan hasil kosong yang disebut berhasil. Jangan menempelkan token privat ke konverter daring yang tidak dikenal: Base64 membuat konten mudah dipindahkan, bukan rahasia.

Mengapa pengujian ASCII saja melewatkan masalahnya

Dua pilihan dekoder perlu diperhatikan: fatal: true menolak UTF-8 tidak valid alih-alih diam-diam memasukkan karakter pengganti; ignoreBOM: true mempertahankan penanda teks di awal. Surrogate UTF-16 tanpa pasangan diganti oleh TextEncoder, sehingga transformasi ini tidak tanpa kehilangan untuk setiap kemungkinan string JavaScript.

Batas yang salah / Unicode → btoa() / Kesalahan karakter bukan byte
Ilustrasi buatan penulis, bukan tangkapan layar aplikasi.

Pengujian lokal peramban yang disimpan memakai Hello, 한글 ™ 🌍. btoa() langsung memunculkan InvalidCharacterError. TextEncoder menghasilkan 22 byte UTF-8, lalu dikodekan menjadi SGVsbG8sIO2VnOq4gCDihKIg8J+MjQ==. Mendekode byte tersebut sebagai UTF-8 mengembalikan kalimat yang sama persis. Ini pengujian lokal sintetis, bukan aplikasi dari kedua pelapor tersebut.

Pengujian yang hanya memakai ASCII dapat menyembunyikan bug. Dalam contoh, btoa("é") menghasilkan 6Q==, sedangkan pengodean UTF-8 terlebih dahulu menghasilkan w6k=. Panggilan pertama tidak memunculkan kesalahan, tetapi byte-nya tidak cocok untuk penerima yang mengharapkan UTF-8. Base64 sendiri tidak memuat deklarasi pengodean karakter.

Dekode dan periksa hasil bolak-baliknya

Base64 bukan enkripsi maupun escaping URL. Tanda plus dapat ditafsirkan khusus dalam parameter kueri; ikuti panduan parameter kueri yang ditautkan. Hindari solusi unescape yang sudah usang, tetapkan batas muatan yang masuk akal, dan jangan pernah membocorkan konten privat hanya untuk mendemonstrasikan kesalahan pengodean.

Diagram alur teks ke 22 byte UTF-8, Base64, lalu kembali ke teks yang sama.
Ilustrasi pendukung, bukan tangkapan layar aplikasi.
Hasil uji Chrome: btoa langsung gagal, sedangkan pengodean UTF-8 dan dekode kembali menghasilkan teks yang sama.
Hasil pengujian lokal tersimpan. Buka gambar untuk memeriksa bukti aslinya.
Sumber, contoh, dan bacaan lanjutan