Base64 Encoding in JavaScript: Complete Guide

← Back to Blog

Base64 Encoding in JavaScript: Complete Guide

· 5 min read

Browser Built-in Methods: btoa and atob

Modern browsers provide two global functions for Base64 operations: btoa() (binary to ASCII, i.e., encoding) and atob() (ASCII to binary, i.e., decoding). These functions are convenient to use and require no external libraries.

// 编码 / Encoding
const encoded = btoa('Hello, World!');
console.log(encoded); // "SGVsbG8sIFdvcmxkIQ=="

// 解码 / Decoding
const decoded = atob('SGVsbG8sIFdvcmxkIQ==');
console.log(decoded); // "Hello, World!"

Note that btoa() only accepts Latin-1 (ISO-8859-1) characters, meaning each character's Unicode code point must not exceed 255. If the input contains Chinese, emoji, or other multibyte Unicode characters, btoa() will throw an InvalidCharacterError exception. This is the most common pitfall for beginners.

Handling Unicode Strings

To Base64 encode strings containing Unicode characters, you need to first convert the string to a UTF-8 byte sequence, then perform Base64 encoding. Modern browsers can use TextEncoder for this step:

// 对 Unicode 字符串进行 Base64 编码
// Base64 encode a Unicode string
function encodeUnicode(str) {
  const bytes = new TextEncoder().encode(str);
  const binary = Array.from(bytes).map(b => String.fromCharCode(b)).join('');
  return btoa(binary);
}

// 解码 Base64 为 Unicode 字符串
// Decode Base64 to Unicode string
function decodeUnicode(base64) {
  const binary = atob(base64);
  const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

console.log(encodeUnicode('你好，世界！'));
// "5L2g5aW977yM5LiW55WM77yB"
console.log(decodeUnicode('5L2g5aW977yM5LiW55WM77yB'));
// "你好，世界！"

Base64 Encoding in Node.js

Node.js doesn't have btoa and atob (although newer versions have added them), and traditionally uses the Buffer class to handle Base64. Buffer natively supports UTF-8 and doesn't have the Unicode limitations of btoa in browsers.

// Node.js Buffer 方式
// Node.js Buffer approach

// 编码 / Encode
const text = '你好，World！';
const encoded = Buffer.from(text, 'utf8').toString('base64');
console.log(encoded);

// 解码 / Decode
const decoded = Buffer.from(encoded, 'base64').toString('utf8');
console.log(decoded); // "你好，World！"

// 编码文件为 Base64
// Encode a file to Base64
const fs = require('fs');
const fileBuffer = fs.readFileSync('./image.png');
const base64Image = fileBuffer.toString('base64');
console.log(`data:image/png;base64,${base64Image}`);

Node.js v16+ provides btoa and atob in the global scope for browser API compatibility. But for server-side applications, Buffer is still recommended as it's more flexible and can directly handle binary data streams.

Base64URL Encoding and Decoding

When handling JWT tokens or placing Base64 in URLs, you need to use the Base64URL variant. Base64URL replaces + with -, / with _, and removes padding =. Here's an implementation in the browser:

// Base64URL 编码
// Base64URL encoding
function toBase64URL(str) {
  return btoa(str)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

// Base64URL 解码
// Base64URL decoding
function fromBase64URL(base64url) {
  const base64 = base64url
    .replace(/-/g, '+')
    .replace(/_/g, '/');
  // 补全填充 / Add padding
  const padded = base64 + '=='.slice(0, (4 - base64.length % 4) % 4);
  return atob(padded);
}

Using Base64 with the Fetch API

When using the Fetch API to send HTTP requests, you sometimes need to send Base64 data as the request body, or decode Base64 data in the response. The following example shows how to handle both scenarios:

// 发送包含 Base64 图片的 POST 请求
// Send POST request with Base64 image
async function uploadImageAsBase64(file) {
  const reader = new FileReader();
  const base64 = await new Promise((resolve) => {
    reader.onload = (e) => resolve(e.target.result.split(',')[1]);
    reader.readAsDataURL(file);
  });

  const response = await fetch('/api/upload', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ image: base64 })
  });
  return response.json();
}

Converting File Objects to Base64

In browsers, a file selected by the user through an input[type=file] is a File object (a subclass of Blob). The FileReader API can convert it to a Base64 string. This is a common pattern for frontend file upload handling and preview:

// 将 File 转换为 Base64
// Convert File to Base64
function fileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result); // data URI
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

// 使用示例 / Usage
const input = document.querySelector('input[type=file]');
input.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const dataURI = await fileToBase64(file);
  document.querySelector('img').src = dataURI;
});

Common Errors and Debugging

The most common error is InvalidCharacterError: The string to be encoded contains characters outside of the Latin1 range, caused by calling btoa() directly on a string containing multibyte characters like Chinese. The solution is to use the TextEncoder method or encodeURIComponent trick introduced earlier.

Another common issue is getting garbled text after decoding, usually because the original data was encoded with a charset other than UTF-8. In such cases, use TextDecoder with the correct charset name, such as new TextDecoder('gbk') to decode Simplified Chinese GBK-encoded data.

Try the online tool now — no installation, completely free.

Open Tool →