깨진 zip 파일명 복원 코드가 멀쩡한 이름을 물음표로 바꿨다
커뮤니티용 텔레그램 봇은 사용자가 올린 zip 안에서 필요한 문서를 파일명으로 골라낸다. 2026년 10월 초, 맥에서 다시 압축한 zip에서 한글 파일명이 깨져 문서를 못 찾는 문제가 있어 이름 복원 함수를 넣었다. 그런데 그 직후 다른 zip 하나가 이렇게 실패했다.
필요한 파일을 찾지 못했습니다
복원 로직을 넣기 전의 코드였으면 통과했을 파일이었다. 로그에 찍힌 이름은 이런 꼴이었다.
???/?????….docx
한글이 전부 물음표로 바뀌어 있었다. 복원 코드가 멀쩡한 이름을 망가뜨린 회귀였다.
처음 넣은 복원 함수
zip 항목 이름은 일반 목적 비트 플래그의 11번 비트(0x800)로 인코딩이 갈린다. APPNOTE는 이 비트가 켜져 있으면 파일명이 UTF-8이어야 한다고 적는다. 꺼져 있을 때 파이썬 zipfile이 cp437로 읽는다는 점은 이 문서 앞부분에서 확인하지 못했다. zipfile 문서도 플래그가 metadata_encoding보다 우선한다는 정도만 말한다. 변경 기록에서 확인되는 것은 이렇다. 비트가 꺼진 zip에서 zipfile이 cp437로 깨뜨린 이름은 encode("cp437")로 되돌리면 원래 바이트가 나오고, 그 바이트를 다시 디코딩하면 한글이 된다.
처음 넣은 복원은 이 관찰에 기대어 만들었다.
name = info.filename
if not info.flag_bits & 0x800:
raw = name.encode("cp437", errors="replace")
for enc in ("utf-8", "cp949"):
try:
name = raw.decode(enc)
break
except UnicodeDecodeError:
continue
UTF-8 비트가 없으면 이름을 cp437 바이트로 되돌리고, UTF-8과 cp949 순으로 디코딩을 시도한다. 맥의 zip이 만든 파일과 한국어 윈도우가 만든 파일을 테스트로 재현해 통과시켰고, 같은 함수에서 자모가 분리된 이름(NFD)도 NFC로 모았다.
물음표는 인코딩 단계에서 생겼다
문제의 zip은 UTF-8 비트가 꺼져 있었다. 그래서 위 분기로 들어갔는데, 이름이 이미 한글이었다. "한글".encode("cp437")은 cp437에 없는 글자라 원래 UnicodeEncodeError가 난다. errors="replace"를 줬기 때문에 예외 대신 글자마다 ?가 들어갔고, 그 바이트열은 어떤 디코더로 읽어도 물음표 문자열이었다. 결과가 ???/????? 꼴이었던 이유다.
예외가 났어야 할 자리를 replace가 덮었다. 이 인자는 “깨져도 일단 진행”하려고 붙였을 텐데, 그 진행이 멀쩡한 데이터를 바꿔 버렸다.
이미 읽힌 이름은 어디서 왔나
이 zip은 UTF-8 비트는 없지만 Unicode Path 보조 필드(0x7075)를 갖고 있었다. APPNOTE에 따르면 이 Info-ZIP Unicode Path Extra Field에는 UTF-8 이름이 들어 있고, 헤더 이름의 CRC-32를 함께 저장해 헤더 이름이 바뀌었는지 확인한다. 커밋 메시지는 이 필드 덕에 zipfile이 이미 한글 이름을 제대로 읽는다고 적었다. 파이썬 문서에는 이 필드 이야기가 없어서 zipfile 내부가 직접 처리하는지는 소스로 확인하지 못했다. 변경 기록에서 확인되는 것은 이 모양의 zip을 테스트에서 직접 만들어 넣었다는 점까지다.
그러니 비트가 꺼져 있다는 사실만으로는 이름이 깨졌는지 알 수 없다. 이름의 출처가 세 가지다.
- UTF-8 비트가 켜진 이름. 그대로 쓴다.
- 비트가 꺼진 레거시 코드페이지 이름.
zipfile이 cp437로 읽은 결과라 되돌려 다시 디코딩해야 한다. - 비트는 꺼졌지만 Unicode Path 필드로 이미 한글이 된 이름. 건드리면 안 된다.
처음 함수는 세 번째를 두 번째로 취급했다.
되돌아가는 이름만 고친다
판별 기준은 단순했다. cp437로 정확히 되돌아가는 이름은 zipfile이 cp437로 읽은 결과이므로 복원 대상이고, 안 되돌아가면 이미 진짜 이름이다.
name = info.filename
if not info.flag_bits & 0x800:
try:
raw = name.encode("cp437")
except UnicodeEncodeError:
raw = None # 이미 진짜 이름
if raw is not None:
for enc in ("utf-8", "cp949"):
try:
name = raw.decode(enc)
break
except UnicodeDecodeError:
continue
errors="replace"를 빼고 예외를 분기 조건으로 쓴다. 위 예시는 읽기 쉽게 구조를 조금 풀어 쓴 것이다. 원본의 except 절은 확인한 diff가 잘려 있어서 같은 모양이라고 단정하지 않는다.
테스트는 파일 모양을 바이트로 만들었다
회귀 테스트는 그 zip의 모양을 직접 조립했다. ZipInfo를 상속해 이름을 cp949 바이트로 쓰면서 UTF-8 비트는 끄고, 진짜 이름을 담은 0x7075 필드를 extra에 붙인다. 필드는 <HH로 헤더 ID와 길이를 쓰고, 본문은 버전 1바이트, 헤더 이름의 CRC-32 4바이트, UTF-8 이름 순이다. 앞서 두 가지(맥 zip 모양과 한국어 윈도우 모양) 사이에 세 번째 케이스를 넣은 셈이다.
수정 뒤에는 실제로 문제가 났던 zip으로 한 번 더 돌려 필요한 파일이 골라지는 것을 확인했고, 맥에서 재압축한 쪽도 그대로 통과했다.
아직 못 푼 것은 이름의 출처를 판별하는 방식이다. flag_bits와 cp437 왕복만 보고 있어서, 어느 경로로 읽힌 이름인지 zipfile이 알려 주지는 않는다. 다음에 압축 프로그램이 하나 더 늘면 먼저 볼 것은 그 zip의 플래그 비트와 보조 필드 목록이다.