정의 및 사용 방법

Window 객체의 btoa() 함수는 주어진 이진 문자열(문자열의 각 문자가 이진 데이터 바이트로 처리되는 문자열, 예: 숫자, 알파벳)을 Base64로 인코딩한 ASCII 코드로 구성된 문자열로 반환합니다.

이 함수는 웹 클라이언트 환경에서 JSON, 데이터 URI 등 텍스트 기반의 통신 채널에 이진 문자열 타입 데이터를 손상 없이 안전하게 전송할 때 주로 사용됩니다.

주의할 점 - 멀티바이트 문자열 처리

btoa() 함수는 주어진 이진 문자열을 처리하도록 고안되었습니다.
이진 문자열이란 숫자, 영어 알파벳, 일부 특수 기호 등 문자열의 각 문자가 1바이트 단위로 처리되는 문자열을 말합니다.

하지만 한국어, 일본어, 중국어, 이모지와 같은 문자는 멀티바이트 문자열에 해당합니다.

btoa() 함수는 멀티바이트 문자열을 처리할 수 없습니다. InvalidCharacterError와 같은 예외가 발생합니다.

구문

JavaScript 
btoa(stringToEncode)

매개변수

btoa() 함수의 매개변수
stringToEncode 인코딩할 이진 문자열입니다.
(U+0000 ~ U+00FF)

반환 값

stringToEncode를 Base64로 인코딩한 ASCII 코드로 구성된 문자열로 반환합니다.

예외

stringToEncode에 이진 문자열이 아닌 멀티문자열이 포함되어 있을 경우에는 InvalidCharacterError가 발생합니다.

예제

아래 예제들은 btoa() 함수의 기본 사용법부터, 실제 활용까지 보여줍니다.

기본 인코딩

btoa() 함수는 이진 문자열(예: 숫자, 알파벳)을 입력받아 Base64로 인코딩한 ASCII 코드로 구성된 문자열로 반환합니다. 이 예제는 가장 기본적인 작동 방식을 보여줍니다.

JavaScript 
const text = "Hello, World!";
const encoded = btoa(text);

console.log(encoded); // 출력: SGVsbG8sIFdvcmxkIQ==

데이터 URI로 HTML에 삽입

btoa() 함수는 사용해서 SVG 코드를 인코딩하면 data: 스킴이 접두어로 붙은 URL를 사용해서 HTML에 인라인으로 삽입할 수 있습니다.

JavaScript 
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
                <text x="0" y="15">Hi</text>
             </svg>`;
const encodedSVG = btoa(svg);
const dataURI = `data:image/svg+xml;base64,${encodedSVG}`;

// HTML <img> 태그에 삽입
const img = document.createElement("img");
img.src = dataURI;
document.body.appendChild(img);

코드 부연설명
createElement() 함수는 새로운 HTML 요소를 생성해서 반환합니다.

코드 부연설명
appendChild() 함수는 노드를 특정 노드의 마지막 자식으로 추가합니다.

데이터 URI의 구문은 다음과 같습니다.

  • data:: Data URI 스키마의 시작을 알리는 부분입니다. 모든 Data URI는 이 접두사로 시작합니다.
  • <mediatype>: MIME 타입을 지정합니다.
  • base64: 데이터가 Base64 인코딩되어 있음을 나타냅니다. 이 부분은 브라우저에게 쉼표(,) 뒤에 오는 문자열을 Base64로 디코딩해야 한다고 알려줍니다.

JWT 토큰 페이로드 디코딩

btoa()와 atob()는 Base64 인코딩/디코딩에 사용되므로, 실제 웹 개발에서는 JWT(Json Web Token)와 같은 토큰 처리에도 활용할 수 있습니다. 아래 예제에서는 JWT 토큰의 페이로드 부분을 추출하고 디코딩하여 JSON 객체로 확인하는 과정을 보여줍니다.

부연설명
atob() 함수는 Base64로 인코딩된 ASCII 코드 문자열 데이터를 디코딩합니다

JavaScript 
// 예시 JWT 토큰 (실제 토큰은 훨씬 길 수 있습니다)
const token = "eyJhbGciOiJIUInR5cCI6IkpXVCJ9.eyJ1c2VImlhdCI6MTY3ODA0ODgwMH0.SignaturePart";

// 1. 페이로드(두 번째 부분) 추출
// JWT는 "헤더.페이로드.서명" 형태로 구성되므로 split('.')로 나눕니다
const payloadBase64 = token.split('.')[1];
console.log(`추출된 페이로드(Base64): ${payloadBase64}`);

// 2. atob()를 사용하여 디코딩 (Base64 → JSON 문자열)
// btoa()는 인코딩, atob()는 디코딩 용도로 사용됩니다
const decodedJsonString = window.atob(payloadBase64);
console.log(`디코딩된 JSON 문자열: ${decodedJsonString}`);

// 3. JSON.parse()로 문자열을 객체화하여 정보 확인
const payloadObject = JSON.parse(decodedJsonString);
console.log(`사용자 ID: ${payloadObject.userId}`);
console.log(`토큰 만료 시간(exp): ${new Date(payloadObject.exp * 1000)}`);

// ⚠️ 주의:
// 실제 JWT 사용 시 민감 정보 처리에 주의하고, 
// 클라이언트에서 디코딩만으로 인증 여부를 판단하면 안 됩니다.

호환성

btoa() 함수의 호환성
메서드
데스크탑 Chrome
Chrome
데스크탑데스크탑 Edge
Edge
데스크탑 Firefox
Firefox
Safari
Safari
Node.js
Node.js
btoa() 4 12 1 3 16
웹 워커(Web Workers) 환경에서 사용 30 12 1 10 16

명세서

btoa() 함수의 명세서 사양
명세서 사양
btoa() HTML
#dom-btoa-dev

참고문헌

같이 보기