"invalid base64 string" 및 일반적인 Base64 디코딩 오류 해결: 완전 가이드

Base64는 널리 사용되는 이진-텍스트 인코딩 스킴입니다. HTML에 이미지 포함, 이메일 첨부 파일 전송(MIME을 통해) 또는 URL에서 소량의 이진 데이터 전달과 같이 텍스트 데이터를 처리하도록 설계된 매체를 통해 데이터를 전송하는 데 필수적입니다.

그러나 개발자들은 invalid base64 string, base64 decode error 또는 난해한 Uncaught DOMException: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.와 같은 오류에 자주 직면합니다.

이 가이드에서는 이러한 오류가 발생하는 이유와 이를 영구적으로 해결하는 방법을 살펴보겠습니다.

1. 일반적인 Base64 오류 메시지

프로그래밍 언어나 환경에 따라 다음과 같은 오류 메시지가 표시될 수 있습니다.

JavaScript (atob): InvalidCharacterError: 'atob' failed: The string to be decoded is not correctly encoded. (atob failed 오류)
Python (base64): binascii.Error: Incorrect padding (base64 padding error)
Java: java.lang.IllegalArgumentException: Illegal base64 character
Go: illegal base64 data at input byte ...

2. 주요 원인 및 해결 방법

2.1 누락되거나 잘못된 패딩 (Padding Error)

Base64 문자열의 길이는 4의 배수여야 합니다. 데이터가 충분히 길지 않으면 등호(=)로 "패딩"됩니다. 이것이 누락되거나 너무 많으면 디코더가 실패하고 base64 padding error가 발생합니다.

오류 내용: Incorrect padding 예: SGVsbG8 (길이가 7이며, 패딩을 포함하여 8이어야 함: SGVsbG8=)

해결 방법: = 문자를 추가하여 문자열 길이를 4의 배수로 만듭니다.

function fixPadding(base64Str) {
  while (base64Str.length % 4 !== 0) {
    base64Str += '=';
  }
  return base64Str;
}

2.2 허용되지 않는 문자 (공백, 줄바꿈 등)

표준 Base64는 A-Z, a-z, 0-9, +, / 및 =만 사용합니다. 문자열에 공백, 탭, 줄바꿈 또는 기타 특수 문자가 포함되어 있으면 많은 디코더에서 illegal character 오류를 발생시킵니다.

오류 내용: Uncaught DOMException: Failed to execute 'atob' ... contains illegal characters

해결 방법: 디코딩하기 전에 공백이나 Base64가 아닌 문자를 제거하여 문자열을 정리합니다.

const cleanBase64 = rawBase64.replace(/[^A-Za-z0-9+/=]/g, "");
const decoded = atob(cleanBase64);

2.3 URL-Safe Base64 vs. 표준 Base64

표준 Base64는 +와 /를 사용합니다. 그러나 이러한 문자는 URL에서 특별한 의미를 갖습니다. 이를 해결하기 위해 "URL-safe Base64"는 +를 -로, /를 _로 바꿉니다. atob와 같은 표준 디코더는 이러한 URL-safe 문자를 만나면 실패하며 invalid base64 string 오류가 발생할 수 있습니다.

오류 내용: invalid base64 string (- 또는 _로 인해 발생)

해결 방법: 디코딩하기 전에 URL-safe 문자를 표준 문자로 바꿉니다.

const standardBase64 = urlSafeBase64.replace(/-/g, '+').replace(/_/g, '/');
const decoded = atob(standardBase64);

2.4 다중 바이트 문자(UTF-8) 디코딩

JavaScript의 atob()는 Latin1 문자만 처리합니다. 중국어, 한국어, 일본어 또는 이모지와 같은 UTF-8 텍스트를 나타내는 Base64 문자열을 디코딩하려고 하면 텍스트가 깨지거나 decodeURIComponent와 함께 사용할 때 URI malformed 오류가 발생할 수 있습니다.

해결 방법: 적절한 UTF-8 디코딩 방법을 사용하세요:

function b64DecodeUnicode(str) {
    return decodeURIComponent(atob(str).split('').map(function(c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
    }).join(''));
}

2.5 "The string to be decoded is not correctly encoded"

이것은 JavaScript atob()의 포괄적인 base64 decode error입니다. 보통 다음 두 가지 중 하나를 의미합니다:

문자열에 A-Z, a-z, 0-9, +, /, = 범위를 벗어난 문자가 포함되어 있습니다.
문자열의 길이(패딩 제외)가 4n + 1(예: 5, 9, 13자)이며, 이는 유효한 Base64 문자열에서 수학적으로 불가능합니다.

3. 예방 및 모범 사례

항상 정리하기: 디코딩하기 전에 정규식을 사용하여 공백과 줄바꿈을 제거하십시오.
URL-safe 변형 처리: 데이터가 URL에서 오는 경우 - 및 _ 변형이 사용될 수 있다고 가정하십시오.
강력한 라이브러리 사용: Node.js에서 작업하는 경우 atob()보다 훨씬 관대한 Buffer.from(str, 'base64')를 사용하십시오.
디코딩 전 유효성 검사: 애플리케이션 충돌을 방지하기 위해 디코딩을 시도하기 전에 문자열이 유효한 Base64인지 확인하십시오.

const isBase64 = (str) => {
  try {
    return btoa(atob(str)) === str;
  } catch (err) {
    return false;
  }
}

4. FAQ: 자주 묻는 질문

Q: Base64 문자열이 ==로 끝나는 이유는 무엇입니까?

A: 이것들은 패딩 문자입니다. Base64는 3바이트를 4문자로 인코딩합니다. 데이터가 1바이트만 남으면 출력을 4문자 길이로 만들기 위해 ==를 추가합니다. 2바이트가 남으면 =를 추가합니다.

Q: 패딩이 누락된 Base64 문자열을 디코딩할 수 있습니까?

A: Node.js나 Python의 base64와 같은 대부분의 현대적인 라이브러리는 누락된 패딩을 자동으로 처리합니다. 그러나 브라우저의 atob()는 엄격하며 실패합니다. 섹션 2.1에서 설명한 대로 패딩을 수동으로 추가해야 합니다.

Q: Base64는 암호화의 일종입니까?

A: 아니요. Base64는 인코딩이지 암호화가 아닙니다. 누구나 즉시 디코딩할 수 있습니다. AES와 같은 실제 암호화를 함께 사용하지 않고 민감한 정보를 숨기는 데 사용하지 마십시오.

5. 빠른 확인 도구

오류가 발생하고 이유를 알 수 없는 경우 문자열을 당사의 Base64 인코더 및 디코더 에 붙여넣으십시오. 당사의 도구는 다음을 수행합니다:

URL-safe 문자를 자동으로 처리합니다.
누락된 패딩 을 수정합니다.
허용되지 않는 문자 를 강조 표시합니다.
UTF-8 (Unicode)을 올바르게 지원합니다.

'invalid base64 string' 및 일반적인 Base64 디코딩 오류 해결 방법