증상

파일 업로드 기능을 운영하다 보면 "첨부파일 이름이 깨져서 받아진다"는 문의를 받게 된다. 웹페이지에는 "한글제목파일.pdf"로 정상 표시되는데, 윈도우에서 내려받으면 저장 창과 탐색기에 "ㅎㅏㄴㄱㅡㄹㅈㅔㅁㅗㄱㅍㅏㅇㅣㄹ.pdf"처럼 자모가 분리되어 나타난다.

인코딩(EUC-KR/UTF-8) 문제로 생기는 뷁문자 같은 깨짐과는 다르다. 원인은 유니코드 정규화 형식의 차이이고, 업로드 시점에 한 줄로 막을 수 있다.

NFC와 NFD

유니코드는 같은 글자를 여러 코드 포인트 조합으로 표현할 수 있고, 이를 하나로 맞추는 규칙을 정규화(Normalization)라고 한다. 한글 파일명에서 문제가 되는 것은 NFC와 NFD 두 가지다.

형식	"한"의 표현	코드 포인트	UTF-8 바이트	주 사용처
NFC (조합)	완성형 음절 1개	U+D55C	3	Windows, 웹, 대부분의 Linux
NFD (분해)	초성 + 중성 + 종성	U+1112 U+1161 U+11AB	9	macOS 파일 시스템

두 문자열은 유니코드상 정준 동등(canonically equivalent)하지만 바이트는 다르다. 렌더러가 NFD 자모를 조합해 주지 않으면 자모가 따로 그려지고, === 비교나 DB 인덱스에서도 서로 다른 값으로 취급된다.

발생 경로

같은 게시판에서도 특정 파일만 깨지는 이유는 파일명이 처음 만들어진 OS가 다르기 때문이다.

macOS에서 만든 파일은 Finder와 파일 시스템을 거치며 파일명이 NFD로 저장되는 경우가 많다.
브라우저의 File.name은 이 이름을 그대로 넘기고, 서버도 별도 처리 없이 저장한다.
다운로드 응답의 Content-Disposition에 NFD 이름이 실리고, Windows의 저장 창과 탐색기는 조합되지 않은 자모를 그대로 표시한다.

웹페이지에서는 브라우저가 텍스트를 렌더링하면서 자모를 조합해 주기 때문에 문제가 보이지 않는다. 그래서 개발 중에는 놓치기 쉽고, 맥 사용자가 올린 파일을 윈도우 사용자가 받을 때 비로소 드러난다.

해결 방법

원칙은 하나다. 시스템에 들어오는 지점에서 NFC로 정규화하고, 내부에서는 NFC만 다룬다. 자바스크립트는 별도 라이브러리 없이 표준 메서드 String.prototype.normalize()로 처리할 수 있다.

const nfd = "\u1112\u1161\u11AB"; // ㅎ + ㅏ + ㄴ
const nfc = nfd.normalize("NFC");  // "한"

nfd.length;  // 3
nfc.length;  // 1
nfd === nfc; // false

업로드 시

input.addEventListener("change", (e) => {
  const file = e.target.files[0];
  const formData = new FormData();
  formData.append("file", file, file.name.normalize("NFC"));
  fetch("/upload", { method: "POST", body: formData });
});

다운로드 시

const name = file.name.normalize("NFC");

정리

다운로드한 파일 이름의 자모가 풀어지는 현상은 macOS의 NFD와 Windows의 NFC가 만나서 생기는 표기 차이다. 파일 내용은 안전하니 이름만 다시 입력하면 되고, 서비스를 만드는 입장이라면 업로드 시점에 normalize("NFC") 한 줄로 예방할 수 있다.

다운로드한 파일 이름의 한글 자모가 풀어지는 이유와 해결법

다운로드한 파일 이름의 한글 자모가 풀어지는 이유와 해결법