이메일 이미지가 안 보이는 이유가 Base64였다 — 인코딩 원리부터 실무 함정까지 2026

오전 9시에 버그 리포트가 들어왔어요. '웰컴 이메일에 프로필 사진이 안 뜬다'는 거예요. 엔지니어 넷이서 90분을 CDN 캐싱 문제로 추정하고 뒤졌는데 아무것도 없었어요. 누군가 MIME 원문을 Base64 디코더에 돌렸더니 바로 나왔어요. 백엔드에서 UTF-8 문자열에 btoa()를 돌리고 있었던 거예요. Latin1 범위를 벗어나는 한글 이름, 이모지가 들어간 닉네임 — 전부 조용히 깨져 있었어요. Base64를 제대로 알았으면 코드 리뷰 20분에 잡을 수 있었던 버그예요.

Base64가 실제로 하는 일

Base64는 바이너리 데이터를 64개의 안전한 ASCII 문자로 변환하는 인코딩 방식이에요. 원래 설계 목적은 이메일(SMTP)처럼 7비트 ASCII만 처리하는 텍스트 전용 시스템에서 바이너리 파일을 안전하게 보내는 거였어요.

• 3바이트(24비트)씩 처리해요 — 3바이트를 6비트짜리 네 덩어리로 쪼개요
• 각 6비트 값을 64개의 출력 가능한 ASCII 문자 중 하나로 매핑해요 (A-Z, a-z, 0-9, +, /)
• 출력은 항상 입력보다 정확히 33% 더 커요 — 텍스트 안전 인코딩의 비용이에요
• 입력 길이가 3으로 나누어지지 않으면 = 패딩 문자로 빈 자리를 채워요

실제 코드에서 Base64가 나오는 곳

Base64는 한 가지가 아니에요. 맥락마다 조금씩 다른 방식으로 나타나요. 어떤 변형인지 알아야 디버깅할 때 시간을 아낄 수 있어요.

• 이메일 첨부파일(MIME): SMTP는 7비트 ASCII 텍스트 전용이에요. PDF를 첨부할 때 메일 클라이언트가 자동으로 Base64 인코딩을 해줘요.
• HTML/CSS Data URI: data:image/png;base64,...로 이미지를 마크업에 직접 임베딩해요. HTTP 요청을 줄이는 대신 33% 용량 증가와 캐싱 포기를 감수해야 해요.
• API 페이로드(JSON): JSON은 텍스트 전용이에요. 이미지, 오디오, PDF를 JSON 바디에 넣으려면 Base64로 인코딩해야 해요.
• JWT 토큰: 점(.)으로 구분된 JWT 세 부분이 전부 URL-safe Base64예요. 헤더, 페이로드, 서명이 각각 그 방식으로 인코딩돼 있어요.
• HTTP Basic 인증: Authorization 헤더에 들어가는 username:password 조합이 Base64 인코딩된 거예요. 암호화가 아니에요.

표준 Base64 vs URL-safe Base64 — 혼용하면 생기는 일

이 둘을 혼용하면 버그가 나요. 표준 Base64로 인코딩한 걸 URL에 넣으면 +가 공백으로 디코딩되고, /가 경로 구분자로 해석돼요. URL이나 HTTP 헤더에 들어가는 건 항상 URL-safe Base64를 써야 해요.

btoa()가 유니코드에서 터지는 이유와 해결법

JavaScript 내장 btoa() 함수는 Latin1 문자만 처리해요. 한글, 이모지, 유니코드 문자를 넘기면 'The string to be encoded contains characters outside of the Latin1 range' 에러를 던져요. 이게 웰컴 이메일 버그의 원인이에요. UTF-8로 먼저 인코딩하는 과정이 필요해요:

// 틀린 방법 — Latin1 범위 밖 문자에서 실패
btoa('안녕하세요') // DOMException 발생

// 맞는 방법 — 전체 UTF-8 처리
function base64Encode(str) {
  return btoa(
    Array.from(new TextEncoder().encode(str))
      .map(byte => String.fromCharCode(byte))
      .join('')
  );
}

function base64Decode(b64) {
  return new TextDecoder().decode(
    Uint8Array.from(atob(b64), c => c.charCodeAt(0))
  );
}

도구 비교: btoa() vs 터미널 vs QuickFigure