[TIL/Amazon S3] 2025/05/17

원민관·2025년 5월 17일

Amazon S3 TIL

[TIL]

목록 보기

181/201

Image Processing Optimization 🎨

0. Overview ✅

Question Content에 포함되는, 이미지를 처리하는 방법에 대해 소개하고자 합니다.

Amazon S3란, 이미지 / 동영상 / 문서 / 백업 데이터 등 다양한 파일을 저장하고 관리할 수 있는, AWS에서 제공하는 클라우드 객체 스토리지 서비스입니다.

Base64로 삽입된 이미지를 WebP 파일로 변환해 AWS S3에 업로드하고, HTML 콘텐츠의 <img> 태그 src를 S3 이미지 URL로 교체하는 이미지 처리 최적화에 대해 설명하고자 합니다.

1. processContentImages() ✅

  async processContentImages(content: string): Promise<string> {
    const parser = new DOMParser();

    const doc = parser.parseFromString(content, "text/html");

    const images = doc.querySelectorAll("img");

    for (const img of images) {
      if (img.src.startsWith("data:image")) {
        try {
          const file = await this.convertBase64ToWebPFileWithFallback(img.src);
          const uploadURL = await this.uploadFileToS3(file);
          img.src = uploadURL;
        } catch (error) {
          console.error("Error processing image:", error);
        }
      }
    }

    return doc.getElementsByTagName("body")[0].innerHTML;
  }

질문 제출 버튼을 클릭하는 순간 가장 먼저 동작하게 되는 함수입니다.

이 함수는 HTML 문자열(content)을 받아, 그 안의 이미지 태그 중 base64로 인코딩된 이미지(data:image/...)를 찾아 WebP 형식으로 변환한 뒤 AWS S3에 업로드하고, 해당 이미지 태그의 src를 업로드된 S3 URL로 교체한 후, 최종적으로 수정된 HTML 문자열을 반환합니다.

먼저 base64로 인코딩되었다는 것이 어떤 의미인지 살펴보겠습니다.

이미지는 픽셀의 집합입니다. RGB 색상 모델의 관점에서 보면, 각 픽셀은 0부터 255 사이의 숫자 값으로 표현됩니다. 0이 색상이 전혀 없는 상태라면, 255는 가장 강한 색상을 뜻합니다. 즉, 이미지는 바이너리 데이터입니다.

Base64는 컴퓨터가 처리하는 바이너리(0과 1로 이루어진 이진 데이터)를 텍스트 문자(알파벳, 숫자, 특수기호)로 안전하게 변환하는 인코딩 방식입니다. 이미지를 비롯한 모든 이진 파일은 원래 RGB 값 등으로 구성된 바이너리 데이터지만, HTML이나 JSON 같은 텍스트 기반 환경에서는 그대로 쓸 수 없기 때문에, base64로 인코딩해 텍스트 형태로 바꿔 저장하거나 전송합니다. 이를 통해 이미지 데이터를 문자열로 표현하고 웹 문서나 API 등에 삽입할 수 있게 됩니다.

다음으로 parser에 대해 알아봐야 하겠습니다.

parser는, 문자열 형태의 HTML, XML 같은 문서를 브라우저가 이해하는 DOM(Document Object Model) 객체로 변환해 주는 도구입니다. 텍스트를 DOM 객체로 변환해야 현재의 document에서 이미지 '태그'를 추출할 수 있겠죠.

parser에서 제공하는 parseFromString() 메서드를 통해, 문자열 형태인 content를 HTML 문서 구조(DOM)로 변환합니다.

content에 이미지 한 장을 담아서 전달하면 doc 변수에는 다음과 같은 DOM 정보가 저장됩니다.

 #document (http://localhost:5173/edit)
    <html>
      <head></head>
       <body>
         <p>
          <img src="https://react-nest-bucket.s3.ap-northeast-2.amazonaws.com/images/image-1747463476560.webp">
        </p>
      </body>
    </html>

doc(DOM 객체)에 querySelectorAll() 메서드를 적용하여, 이미지 태그만 추출합니다.

이제 이미지 태그에 포함된 src를 통해 convertBase64ToWebPFileWithFallback() 함수와 uploadFileToS3() 함수를 실행한 뒤, 이미지 URL을 S3의 URL로 교체하고, 변형된 doc의 boby의 첫 번째 요소를 반환하게 됩니다.

<p>
 <img src="https://react-nest-bucket.s3.ap-northeast-2.amazonaws.com/images/image-1747463476560.webp">
</p>

2. convertBase64ToWebPFileWithFallback() ✅

processContentImages() 함수에서 이미지 태그의 src를 추출한 뒤 가장 먼저 실행되는 함수가 바로 convertBase64ToWebPFileWithFallback() 함수입니다.

async convertBase64ToWebPFileWithFallback(base64: string): Promise<File> {
    return new Promise((resolve) => {
      const img = new Image();
      img.src = base64;

      img.onload = () => {
        const canvas = document.createElement("canvas");
        canvas.width = img.width;
        canvas.height = img.height;

        const ctx = canvas.getContext("2d");
        if (!ctx) {
          resolve(this.convertBase64ToOriginal(base64));
          return;
        }

        ctx.drawImage(img, 0, 0);

        canvas.toBlob(
          (blob) => {
            if (blob) {
              const webpFile = new File([blob], `image-${Date.now()}.webp`, {
                type: "image/webp",
              });
              resolve(webpFile);
            } else {
              resolve(this.convertBase64ToOriginal(base64));
            }
          },
          "image/webp",
          0.8
        );
      };

      img.onerror = () => resolve(this.convertBase64ToOriginal(base64));
    });
  }

convertBase64ToWebPFileWithFallback() 함수에 들어오는 base64는 "data:image"로 시작하는 이미지 URL입니다.

const img = new Image();
img.src = base64;

위 과정이 선행되어야 합니다.

base64 문자열은 단순 텍스트 데이터이기 때문에 바로 이미지 파일로 다룰 수 없습니다. 텍스트 데이터를 실제 이미지처럼 브라우저가 인식하고 처리하기 위해서는 Image 객체에 src를 지정하여 이미지를 로드하고 크기나 픽셀 데이터 등을 얻는 과정이 필요합니다.

const canvas = document.createElement("canvas");
canvas.width = img.width;
canvas.height = img.height;

const ctx = canvas.getContext("2d");

if (!ctx) {
  resolve(this.convertBase64ToOriginal(base64));
  return;
}

ctx.drawImage(img, 0, 0);

img.onload는, 이미지가 img.src에 지정된 base64 데이터를 다 읽어서 완전히 로드되면 실행되는 콜백 함수입니다.

웹 페이지에 실제로 표시되지 않는 가상의 <canvas> 요소를 새로 만듭니다. 이미지 변환을 위해 임시로 이미지를 그리게 될 공간에 해당합니다. 이후, 캔버스의 크기를 원본 이미지의 크기 와 동일하게 맞춰서, 이미지가 왜곡 없이 그대로 그려질 수 있도록 합니다.

const ctx = canvas.getContext("2d");

canvas에 getContext("2d") 메서드를 적용한 모습을 확인할 수 있습니다. canvas가 도화지라면, ctx는 도화지에 그림을 그릴 수 있는 붓을 받는 과정입니다. 정확히는 2d 형태의 그림을 그리기 위한 붓을 받은 것입니다. 이후 drawImage() 메서드를 통해 캔버스 좌상단(0,0)부터 그림을 그리기 시작합니다.

  canvas.toBlob(
          (blob) => {
            if (blob) {
              const webpFile = new File([blob], `image-${Date.now()}.webp`, {
                type: "image/webp",
              });
              resolve(webpFile);
            } else {
              resolve(this.convertBase64ToOriginal(base64));
            }
          },
          "image/webp",
          0.8
        );

위 코드가 convertBase64ToWebPFileWithFallback() 함수의 핵심입니다.

Blob은 Binary Large Object의 약자로, 0과 1로 이루어진 이진 데이터입니다. 위 코드는, 캔버스에 그린 그림을 바이너리 데이터로 변환한 뒤 webp 파일 형식으로 다시 반환하는 코드라고 요약할 수 있습니다.

캔버스의 시각적 정보는 메모리에 픽셀 단위로 저장되는데, 이 정보를 바로 webp 파일 형태로 변환하기 어렵기 때문에, 중간 단계로 Blob이라는 범용 이진 데이터 형식으로 먼저 변환해 주는 것입니다.

convertBase64ToWebPFileWithFallback() 함수에서 webp 파일로 변환에 실패하는 모든 상황에서는, convertBase64ToOriginal() 함수를 실행하게 됩니다.

이미지를 더 효율적인 WebP 포맷으로 변환하되, 브라우저가 WebP를 지원하지 않거나 변환에 실패하는 경우를 대비해 원본 JPEG로 돌아가는 안전장치(fallback)를 구현한 함수라고 정리할 수 있겠습니다.

3. convertBase64ToOriginal() ✅

  async convertBase64ToOriginal(src: string): Promise<File> {
    const base = atob(src.split(",")[1]);

    const blob = Uint8Array.from(base, (char) => char.charCodeAt(0));

    return new File([blob], `image-${Date.now()}.jpeg`, { type: "image/jpeg" });
  }

convertBase64ToWebPFileWithFallback() 함수의 예외를 처리하는 함수입니다. WebP 변환에 실패했을 경우 원본 JPEG 파일을 반환하는 함수입니다.

data:image/jpeg;base64,/9j/4AAQSkZJRg...과 같은 형식에서 실제 base64 데이터 부분만 추출합니다. 실제 데이터를 atob() 메서드를 통해 이진 문자열로 변환하게 됩니다. 이후 '이진 문자열'을 실제 바이너리 데이터로 변환한 값이 blob이 됩니다. 해당 바이너리 데이터로 jpeg 파일을 생성하게 되죠.

실제 데이터가 이진 문자열이 되고, 이진 문자열이 실제 바이너리 데이터로 변환되는 과정을 이해해야 합니다.

만약 , 이후의 실제 데이터가 "SGk="라면 이진 문자열은 "Hi"이고 바이트 배열은 [72, 105]가 됩니다.

역으로 생각해 보죠.

H의 ASCII 값은 72(01001000), i의 ASCII 값은 105(01101001)입니다. 이는 총 16비트이죠. 하지만 Base64는 항상 3바이트(24비트) 단위로 데이터를 인코딩하기 때문에, 부족한 1바이트(8비트)는 0으로 패딩하여 아래와 같이 24비트로 만듭니다.

01001000 01101001 00000000

이제 이 24비트를 6비트 단위로 쪼개면 다음과 같습니다.

010010 / 000110 / 100100 / 000000

각 6비트 블록을 10진수로 변환하면 18, 6, 36, 0이 되고, Base64 인코딩 테이블에서 각각에 대응하는 문자는 "S", "G", "k", "A"입니다. 하지만 실제 데이터는 2바이트(Hi)였고, 마지막 바이트는 패딩으로 추가된 것이므로 "A"는 제거되고, 그 자리는 =로 대체됩니다. 따라서 최종 결과는 "SGk="입니다.

Base64는 바이너리 데이터를 텍스트 기반 환경(HTML, JSON 등)에 안전하게 전달하기 위한 인코딩 방식입니다. 이 방식은 다음과 같은 원리로 설계되었습니다.

컴퓨터의 데이터는 일반적으로 8비트(1바이트) 단위로 구성됩니다.

Base64는 6비트 단위로 쪼갭니다. 왜냐하면 6비트는 2^6 = 64개의 값을 표현할 수 있으며, 이는 텍스트로 안전하게 표현할 수 있는 64개의 문자(A-Z, a-z, 0-9, +, /)와 정확히 일치하기 때문입니다.

그런데 8비트와 6비트는 서로 딱 맞아떨어지지 않기 때문에, 6과 8의 최소공배수인 24비트 단위로 묶어 처리하는 것이 가장 효율적입니다.

다음과 같이 인코딩 됩니다.

3개의 8비트(3바이트) = 24비트 → 6비트씩 4조각으로 나누어 4글자로 인코딩

반대로 디코딩 할 때는 다음과 같이 원래대로 복원됩니다.

4개의 Base64 문자 → 각각 6비트 = 24비트 → 3바이트(8비트씩)로 복원

"SGk="는 실제 이미지 데이터 부분에 대한 예시였습니다.

이 값은 base64 인코딩을 거친 값인데 "Hi"를 인코딩하면 "SGk="가 된다는 것을 의미합니다. 반대로 "SGk="를 디코딩 하면, "Hi"가 되겠죠. 이때 "Hi"에 대응되는 바이너리가 [72, 105]가 된다고 이해할 수 있습니다.

4. uploadFileToS3() ✅

  constructor() {
    AWS.config.update({
      accessKeyId: import.meta.env.VITE_AWS_ACCESS_KEY_ID,
      secretAccessKey: import.meta.env.VITE_AWS_SECRET_ACCESS_KEY,
      region: import.meta.env.VITE_AWS_REGION,
    });

    this.s3 = new AWS.S3();
  }

코드 상단에서 S3 Service를 사용하기 위한 기본적인 Configuration 설정을 진행했습니다.

  async uploadFileToS3(file: File): Promise<string> {
    const params = {
      Bucket: import.meta.env.VITE_AWS_BUCKET_NAME,
      Key: `images/${file.name}`,
      Body: file,
      ContentType: file.type,
    };

    return new Promise<string>((resolve, reject) => {
      this.s3.upload(
        params,
        (
          err: Error | null,
          data: AWS.S3.ManagedUpload.SendData | undefined
        ) => {
          if (err) {
            reject(err);
          } else {
            resolve(data?.Location || "");
          }
        }
      );
    });
  }

나름대로의 변환 과정을 거친 이미지 파일을, 최종적으로 S3 Bucket에 업로드하는 로직입니다. 단순한 사용법입니다.

5. Conclusion ✅

HTML 콘텐츠에 포함된, Base64로 인코딩된 이미지를 WebP 형식으로 변환하여 AWS S3에 업로드하는 과정을 설명했습니다.

processContentImages() 함수에서 시작하여, HTML 문서에서 Base64 이미지를 찾아 convertBase64ToWebPFileWithFallback() 함수를 통해 더 효율적인 WebP 포맷으로 변환했습니다. 변환에 실패할 경우에는 convertBase64ToOriginal() 함수로 원본 JPEG 형식을 유지했죠.

최종적으로 uploadFileToS3() 함수를 통해 변환된 이미지를 S3에 업로드하고 HTML의 이미지 태그 src 속성을 S3 URL로 교체함으로써 웹 페이지의 로딩 성능을 향상시키는 이미지 최적화 솔루션을 개발했습니다.

원민관

Write a little every day, without hope, without despair ✍️

이전 포스트

TypeScript Course 🔥

다음 포스트