[TroubleShooting] PDF 프리뷰시 자동 다운로드 현상 해결하기

개요

현재 인턴 중인 곳에서 기존 1차 개발이 되어있던 프로젝트를 보수하고, 새로운 기능을 추가하여 정식 배포를 준비 중에 있다.

그 중 QA 결과로 PDF 프리뷰를 제공하는 페이지에 진입 시 해당 PDF가 자동 다운로드 되는 현상이 발견되어 해결을 요청 받았다.

확인해본 결과 문제 상황은 다음과 같았다.

• 상세 페이지에서 html `<embed>` 태그로 pdf 프리뷰 제공 중
• 일부 pdf를 대상으로 프리뷰가 성공적으로 렌더링 되지 않고, 자동 다운로드 되는 문제 발생

원인 분석

현재 프리뷰를 제공 대상인 pdf는 사용자가 서비스 내에서 업로드한 pdf로, CDN에서 제공하는 url을 사용하여 가져온다.

프리뷰에 성공하는 pdf와 실패하는 pdf의 CDN url로 curl 명령어을 통해 응답 헤더를 확인해보았다.

curl 명령어를 통한 응답 헤더 확인

curl -i [url]

성공 pdf

>curl -I [성공 pdf url]
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 1950360
Connection: keep-alive
Date: Fri, 25 Jul 2025 06:28:03 GMT
Last-Modified: Wed, 12 Feb 2025 09:39:11 GMT
... 생략

실패 pdf

curl -I [실패 pdf url]
HTTP/1.1 200 OK
Content-Type: application/haansoftpdf
Content-Length: 75182
Connection: keep-alive
Date: Fri, 25 Jul 2025 06:22:51 GMT
Last-Modified: Mon, 21 Jul 2025 06:26:48 GMT
... 생략

• 일부 pdf에 대한 CDN 응답에서 Content-Type이 `application/haansoftpdf` 으로 제공되고 있음을 확인하였다.
• 주요 브라우저들은 내장 PDF 뷰어를 제공하지만, 이는 `application/pdf`인 Content-Type에 대해서만 적용된다.
• 이에 따라 프리뷰를 제공하지 못 하고 대신 자동 다운로드 처리되는 듯했다..

원인 파악

그렇다면 왜 일부에 한해서 `application/haansoftpdf` 로 Content-Type이 지정되어 응답되는걸까? 

이유를 알아야 해결이 가능하다.

가설 1. CDN 설정

• CDN에서 명시적으로 Content-Type 설정을 변경한 경우다.
• 이 경우 CDN 설정 수정으로 간단히 해결 가능할 것 같았다. 그렇지만 누가 CDN 설정을 `application/haansoftpdf`으로 바꾼단 말이냐 .. 게다가 일부는 `application/pdf`로 잘 응답이 오고 있으므로 이 가설은 가능성이 낮았다.

가설 2. 업로드 시점 Content-Type 문제

• pdf 자동 다운로드와 관련해 구글링을 해본 결과, 한컴 PDF 뷰어 설치 시 사용자 로컬 환경의 PDF MIME 타입이 `application/haansoftpdf`로 자동 설정된다는 사실을 발견했다..!
  • 발견 블로그1
  • 발견 블로그2
• 해당 레지스트리 설정이 되어있는 사용자가 pdf를 업로드 할 경우 Content-Type이 변경된 채로 그대로 S3에 업로드 되고 있었던 것이다.
• 이 가설을 확인해보기 위해 실제 윈도우 컴퓨터의 레지스트리 설정을
  • pdf : `application/haansoftpdf`로 변경하여 pdf를 업로드하고 확인해본 결과, 프리뷰 실패 & 자동 다운로드 & 헤더 Content-Type : `application/hannsoftpdf`로 응답됨을 확인하였다.
  • pdf : `application/pdf`로 다시 변경하여 pdf를 업로드하고 확인해본 결과, 프리뷰 성공 & 헤더 Content-Type : `application/pdf`로 응답됨을 확인하였다.

해결

가설 2에 의해 문제 상황이 발생하고 있다는 것을 확인하였다.

현재 사용자가 `application/haansoftpdf`로 Content-Type을 지정하여 업로드 요청하고 있으니,

이를 `application/pdf`로 표준화하여 S3에 업로드하도록 로직을 변경하였다.

표준화 매핑 테이블 추가

    // 매핑 테이블
    private static final Map<String, String> CONTENT_TYPE_CORRECTIONS = Map.of(
            "application/haansoftpdf", "application/pdf"
    ); 
    
    // 표준화 함수
    private String normalizeContentType(String originalContentType) {
    return CONTENT_TYPE_CORRECTIONS.getOrDefault(originalContentType, originalContentType);
    }

업로드 로직에 표준화 적용

    PutObjectRequest objectReq = PutObjectRequest.builder()
            .bucket(BUCKET)
            .key(filename)
            .contentType(normalizeContentType(file.getContentType())) // 표준화 적용
            .contentLength(file.getSize())
        .build();

    PutObjectResponse resp = s3Client.putObject(objectReq, RequestBody.fromBytes(file.getBytes()));

테스트

해결 후

• pdf 레지스트리가 `application/pdf` & `application/haansoftpdf` 두 상태로 설정되었을 경우 모두 pdf 업로드시 정상적으로 프리뷰가 작동하는 것을 확인하였다.

고려사항

• 기존 업로드 파일에 대한 일괄 처리
  • 이미 업로드된 파일 중 `application/haansoftpdf`로 저장된 객체는 여전히 프리뷰에 실패하며 자동 다운로드 처리된다.
  • 따라서 필요시 Content-Type 메타데이터를 수정하는 배치 작업이 필요하다.
  • 그렇지만 현재 참여 중인 프로젝트의 경우 정식 배포 중이 아닌 dev 환경이므로 해당 작업은 생략하였다!
  • 만일 배포된 프로젝트 내에서 다음과 같은 문제가 생긴 경우, 해결 후 배치 작업을 수행해주면 될 듯 하다.