AJAX를 이용한 파일 다운로드 시 한글 파일명 깨짐 문제 해결하기

문제 상황 설명

최근 프로젝트에서 AJAX를 사용하여 서버로부터 파일을 다운로드할 때 한글 파일명이 깨지는 현상을 겪었다. 동일한 파일 다운로드 기능을 form 제출 방식으로 구현했을 때는 이러한 문제가 발생하지 않았다.

• 882ECA99EEB84A7ECB18FEDB5B3%84_240715-240726.xlsx -> 이런식으로 한글 깨짐

 

원인 분석

AJAX와 form 제출 방식의 차이점

• Form 제출 방식: 브라우저가 기본적으로 제공하는 다운로드 기능을 활용한다. 브라우저는 Content-Disposition 헤더를 자동으로 처리하고, 파일명 인코딩을 알아서 처리한다. 따라서 Form 형식의 파일다운로드에서는 파일명이 제대로 출력됬다.
• AJAX 방식: XMLHttpRequest 또는 Fetch API를 사용하여 비동기적으로 파일을 요청하고, JavaScript로 파일 다운로드를 처리한다. 이 경우 브라우저가 기본 다운로드 기능을 사용하지 않기 때문에, 파일명 인코딩 처리를 수동으로 해야 한다. AJAX 방식에서는 서버에서 보내는 Content-Disposition헤더를 그대로 받아 처리하기 때문에, 추가적인 인코딩 처리가 필요하다.

Content-Disposition 헤더 처리 방식

• Content-Disposition 헤더는 파일 다운로드 시 파일명을 지정하는 데 사용된다. 이 헤더는 ASCII 문자만을 지원하기 때문에, 한글 파일명은 인코딩되어 전달되어야 한다.
• RFC 5987 표준을 사용하면 파일명을 UTF-8로 인코딩할 수 있다.
• ** RFC 5987에 대한 간단한 설명 : RFC 5987은 HTTP 헤더 필드에 국제화된 문자열을 사용할 수 있도록 정의한 표준이다. 이 표준을 따르면, UTF-8로 인코딩된 문자열을 헤더 필드에 포함시킬 수 있다.

 

해결 방법

클라이언트 측 코드 수정 내용

• 클라이언트 측에서는 서버로부터 받은 파일명을 올바르게 인코딩하여 처리

서버 측 코드 수정 내용

• 서버 측에서는 Content-Disposition 헤더에 파일명을 UTF-8로 인코딩하여 설정

 

코드 예시

1. 문제가 있던 원래 코드

클라이언트 측 코드

fetch('/download', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
    },
})
.then(response => response.blob())
.then(blob => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = '파일명.xlsx'; // 한글 파일명 깨짐
    document.body.appendChild(a);
    a.click();
    a.remove();
});

서버 측 코드

response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
response.setHeader("Content-Disposition", "attachment; filename=\"파일명.xlsx\"");

 

2. 수정된 코드

클라이언트 측 코드

fetch('/download', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
    },
})
.then(response => {
    const disposition = response.headers.get('Content-Disposition');
    const filename = disposition.match(/filename\*?=['"]?([^;\n"]*)['"]?/)[1];
    const decodedFilename = decodeURIComponent(filename.replace(/\+/g, ' '));
    return response.blob().then(blob => {
        const url = window.URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = decodedFilename;
        document.body.appendChild(a);
        a.click();
        a.remove();
    });
});

서버 측 코드

import org.apache.commons.codec.net.URLCodec;

response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
String fileName = "파일명.xlsx";
URLCodec codec = new URLCodec();
String encodedFileName = codec.encode(fileName, "UTF-8");
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + encodedFileName);

 

 

 

참고 자료

관련 RFC 문서 링크

• RFC 5987: HTTP 헤더 필드에 대한 국제화된 문자열 지원

기타 도움이 된 자료들

• MDN Web Docs: Content-Disposition
• Spring Framework Documentation