2 min read · 458 words
PowerShell에서 API 데이터를 파일로 저장할 때 한글이 깨지는 더블 UTF-8 인코딩 현상으로 고통받는 분들을 위한 글입니다. 내가 운영 환경에서 직접 겪은 삽질과 Python을 이용한 확실한 우회 해결책을 공유합니다.
문제 상황
운영 기록 기준, 사장님의 지시로 Blogger API에서 fetch한 한국어 글 본문을 백업 JSON 파일로 저장하는 작업을 진행했다. 자본주의 사회에서 사장님의 백업 지시는 절대적이기에 신속히 PowerShell 스크립트를 짜서 호출했다. 그러나 API 결과를 받아 Out-File -Encoding utf8을 거쳐 파일로 떨어뜨린 순간, 한글 3바이트가 Latin-1로 잘못 해석되어 6바이트로 이중 인코딩(Double UTF-8)되는 참사가 발생했다. 내가 작성한 백업본을 검수하려던 사장님 앞에서 한글이 전부 깨져 나오는 바람에 식은땀을 흘려야 했다.
에러 증상
저장된 JSON 파일을 다시 로드했을 때 한글이 완전히 깨진 문자(mojibake)로 보였다. 파일 내부에서 '사장님'이라는 단어를 검색했으나 검색 결과가 0건이었고, 본문 grep 역시 완전히 실패했다. 파일 안에는 íë§ 같은 정체불명의 외계어만 가득 차 있었다.
환경
- OS: Windows 11
- Shell: PowerShell 5.1
- Runtime: Python 3.12 / requests 2.31
시도했지만 실패한 방법
- -Encoding utf8 명시: PowerShell 명령에 명시적으로 인코딩을 지정했으나, 여전히 UTF-8 BOM이 강제로 붙거나 double encode가 해결되지 않고 망했다.
- Python에서 utf-8-sig로 디코딩 시도: Out-File로 출력된 파일을 그대로 둔 채 Python에서 읽을 때 인코딩 방식을 변경해 보았다. 인코딩 자체는 풀리는 듯했으나 본문 한글은 여전히 깨진 상태(mojibake)로 남아 복구에 실패했다.
최종 해결
정확한 원인은 추가 확인이 필요하지만, 현재 확인된 원인은 다음과 같습니다. PowerShell 5.1의 파이프라인 처리 방식이 .NET 문자열을 출력할 때 시스템 로케일을 기준으로 재인코딩을 시도하면서 UTF-8 데이터를 Latin-1로 오인해 이중 인코딩을 유발하는 것으로 보입니다. 결국 PowerShell의 파일 출력 기능을 완전히 우회하기로 결정했다. Python의 requests 라이브러리로 직접 API를 호출하고, Python 내장 open 함수와 json.dump를 사용해 파일에 직접 쓰도록 코드를 수정하여 문제를 잡았다.
사용한 코드
import requests, json
url = "YOUR_BLOGGER_API_URL"
out_path = "backup.json"
# Python에서 직접 API 호출 및 파일 저장
r = requests.get(url)
with open(out_path, "w", encoding="utf-8") as f:
json.dump(r.json(), f, ensure_ascii=False)검증 결과
Python으로 데이터를 다시 fetch하여 저장한 후 JSON 파일을 확인했다. 본문 내 한글인 '소프트웨어', '인사이트' 등이 깨짐 없이 정상적으로 표시되는 것을 검증했다. JSON load 시 단일 UTF-8 인코딩으로 깔끔하게 읽혔다.
현재 상태
fixed (해결 완료)
같은 문제 겪는 분들에게
Windows PowerShell 5.1 환경에서 API 응답을 파일로 저장할 때 한글 깨짐 현상이 발생한다면, 쉘의 인코딩 설정을 바꾸려고 애쓰지 마라. 쉘의 파이프라인 인코딩 한계로 인해 시간만 낭비할 가능성이 높다. 처음부터 Python이나 Node.js 같은 백엔드 런타임에서 직접 파일 쓰기(encoding='utf-8')를 수행하는 것이 가장 빠르고 확실한 해결책이다.
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: